@mind-fold/open-flow 0.1.17 → 0.2.2

package/dist/templates/markdown/structure/flows/code-reuse-thinking-guide.md.txt

@@ -0,0 +1,343 @@
+# Code Reuse Thinking Guide
+
+> **Purpose**: Help you notice patterns and reduce duplication before it becomes tech debt.
+
+> **Related**: Before writing code, read the [Pre-Implementation Checklist](./pre-implementation-checklist.md) to catch reuse opportunities earlier.
+
+---
+
+## Why This Guide?
+
+**Duplicated code is a symptom of "didn't think of abstraction".**
+
+When you write similar code multiple times:
+- Bugs need to be fixed in multiple places
+- Changes require updating multiple files
+- Inconsistencies creep in over time
+- Codebase becomes harder to understand
+
+This guide helps you **recognize reuse opportunities** before they become problems.
+
+---
+
+## The Core Question
+
+Before writing code, ask:
+
+> **"Is there a pattern here that already exists or should be abstracted?"**
+
+---
+
+## Pattern Recognition Checklist
+
+### 1. Schema/Type Patterns
+
+**Trigger**: You're defining a new type with common fields (success, error, etc.).
+
+**Questions**:
+- [ ] Is this the same structure as other types?
+- [ ] Could a base type/schema be extended?
+- [ ] Are there utility functions that could generate this?
+
+**Example - Before**:
+```typescript
+// File 1, 2, 3... same pattern 30+ times
+export const createUserOutput = z.object({
+  success: z.boolean(),
+  error: z.string().optional(),
+  user: userSchema.optional(),
+});
+```
+
+**Example - After**:
+```typescript
+// common.ts - one abstraction
+export function createOutputSchema<T extends z.ZodRawShape>(shape: T) {
+  return z.object({
+    success: z.boolean(),
+    error: z.string().optional(),
+  }).extend(shape);
+}
+
+// Usage
+export const createUserOutput = createOutputSchema({ user: userSchema.optional() });
+```
+
+---
+
+### 2. Function/Logic Patterns
+
+**Trigger**: Writing a function that does something similar to existing code.
+
+**Questions**:
+- [ ] Is there a function that does 80% of what I need?
+- [ ] Can I extract common logic and parameterize the difference?
+
+**Example - Before**:
+```typescript
+// In multiple files
+function createTodo(input) {
+  const parseResult = schema.safeParse(input);
+  if (!parseResult.success) {
+    return { success: false, error: formatError(parseResult.error) };
+  }
+  // ... specific logic
+}
+```
+
+**Example - After**:
+```typescript
+// Shared validation wrapper
+function withValidation<TInput, TOutput>(
+  schema: z.ZodSchema<TInput>,
+  handler: (input: TInput) => TOutput
+) {
+  return (rawInput: unknown) => {
+    const parseResult = schema.safeParse(rawInput);
+    if (!parseResult.success) {
+      return { success: false, error: formatError(parseResult.error) };
+    }
+    return handler(parseResult.data);
+  };
+}
+
+// Usage - specific logic only
+const createTodo = withValidation(todoSchema, (input) => { /* ... */ });
+```
+
+---
+
+### 3. Component Patterns
+
+**Trigger**: Creating a UI component similar to existing ones.
+
+**Questions**:
+- [ ] Is there a base component I can extend or compose?
+- [ ] Are props similar to another component?
+
+**Example - Before**:
+```tsx
+// TodoCard.tsx
+<div className="rounded-lg border p-4 shadow-sm">
+  <h3>{todo.title}</h3>
+  <p>{todo.description}</p>
+  <Badge>{todo.status}</Badge>
+</div>
+
+// JournalCard.tsx (almost identical)
+<div className="rounded-lg border p-4 shadow-sm">
+  <h3>{journal.title}</h3>
+  <p>{journal.content}</p>
+  <Badge>{journal.date}</Badge>
+</div>
+```
+
+**Example - After**:
+```tsx
+// Card.tsx - reusable base
+function Card({ title, content, badge }: CardProps) {
+  return (
+    <div className="rounded-lg border p-4 shadow-sm">
+      <h3>{title}</h3>
+      <p>{content}</p>
+      {badge && <Badge>{badge}</Badge>}
+    </div>
+  );
+}
+
+// Usage
+<Card title={todo.title} content={todo.description} badge={todo.status} />
+```
+
+---
+
+### 4. UI Display Constants (Labels, Icons, Colors)
+
+**Trigger**: Changing a display label, icon, or color for a domain concept.
+
+**Questions**:
+- [ ] Is this display value defined in multiple components?
+- [ ] Should there be a shared config for this domain concept?
+
+**The Problem**: Same domain concept displayed in multiple components, each with its own config. Changing one, forgetting others → inconsistency.
+
+**Example - Before (bug)**:
+```tsx
+// TodoColumn.tsx
+const stateConfig = { open: { label: "Open", ... } };  // ✅ Updated
+
+// TodoDetailPanel.tsx (FORGOT!)
+const stateConfig = { open: { label: "Todo", ... } };  // ❌ Still old
+
+// Result: Column shows "Open", Detail panel shows "Todo"
+```
+
+**Example - After**:
+```tsx
+// shared/constants/todo.ts - Single source of truth
+export const TODO_STATE_CONFIG = {
+  open: { label: "Open", icon: OpenIcon, colorClass: "text-muted" },
+  // ...
+};
+
+// Both components import and use the same config
+```
+
+**Search pattern**:
+```bash
+rg "stateConfig|StateConfig|state.*label" --type tsx
+```
+
+---
+
+### 5. Visual-Logic Consistency
+
+**Trigger**: Implementing logic that determines how something is displayed (sorting, filtering).
+
+**Questions**:
+- [ ] Is there already a visual distinction for this concept?
+- [ ] Does the logic use the **same criteria** as the visual representation?
+
+**The Problem**: Visual representation and logic use different criteria → inconsistent behavior.
+
+**Example - Before (bug)**:
+```typescript
+// Frontend: Icon shows folder if node has children
+if (hasChildren) return <FolderIcon />;  // Uses: children.length > 0
+
+// Backend: Sorting puts "folders" first based on content
+const isFolder = currentVersion > 0;  // Uses: different criteria!
+
+// Result: Icon and sort order don't match
+```
+
+**Example - After**:
+```typescript
+// Both use the same criteria: hasChildren
+const isFolder = children.length > 0;
+```
+
+**Rule**: If users see a visual distinction, the underlying logic must use the **exact same criteria**.
+
+---
+
+### 6. Cross-Layer Shared Constants
+
+**Trigger**: Same value needed in both frontend and backend.
+
+**Questions**:
+- [ ] Is this value used in multiple files?
+- [ ] Would changing it require updating multiple places?
+
+**Example - Before (bug)**:
+```typescript
+// Backend
+const BATCH_SIZE = 15;
+
+// Frontend file1, file2, file3... each defines
+const BATCH_SIZE = 15;  // Duplicated 5 times!
+```
+
+**Example - After**:
+```typescript
+// shared/constants/config.ts - Single source of truth
+export const SYNC_CONSTANTS = {
+  BATCH_SIZE: 15,  // API limit
+  DEBOUNCE_MS: 2000,
+} as const;
+
+// Both layers import from shared
+import { SYNC_CONSTANTS } from "@shared/constants";
+```
+
+---
+
+## When to Abstract vs. Duplicate
+
+**Abstract when**:
+- Pattern repeats 3+ times
+- Logic is identical (not just similar)
+- Changes should propagate to all uses
+
+**Duplicate when**:
+- Pattern only appears 2 times
+- Logic might diverge in the future
+- Abstraction would be confusing
+
+**Rule of thumb**: 
+> "Duplication is cheaper than the wrong abstraction" — Sandi Metz
+
+But once you see 3+ occurrences, it's time to abstract.
+
+---
+
+## Pre-Modification Checklist
+
+**Before changing any value, ALWAYS search first:**
+
+```bash
+# Search for the value you're about to change
+rg "Todo" --type tsx
+rg "stateConfig|priorityConfig" --type tsx
+
+# Search for the concept
+rg "open.*label|label.*open" --type tsx
+```
+
+**Questions**:
+- [ ] How many files define this value?
+- [ ] Should this be a shared constant instead?
+- [ ] If I change it here, where else needs to change?
+
+**The rule**: If you find the same value in 2+ places, **extract to shared constant first**, then make the change in one place.
+
+---
+
+## Quick Decision Tree
+
+```
+You're about to write some code
+    │
+    ├─ Does similar code exist?
+    │   ├─ Yes → Can you reuse/extend it?
+    │   │   ├─ Yes → Reuse it
+    │   │   └─ No → Why not? (might need abstraction)
+    │   └─ No → Continue
+    │
+    ├─ Is this the 3rd time writing this pattern?
+    │   ├─ Yes → Time to abstract
+    │   └─ No → OK to duplicate for now
+    │
+    └─ Done
+```
+
+---
+
+## Lessons Learned
+
+| Situation | Mistake | Solution |
+|-----------|---------|----------|
+| 30+ Output schemas | Didn't abstract base schema | Create `createOutputSchema()` |
+| Changed label in one place | Forgot other components | Extract to shared constants |
+| Icon uses criterion A, sort uses B | Visual-logic mismatch | Unify to same criterion |
+| Same constant in 6 files | No shared constants | Create `@shared/constants/` |
+| Same hook logic in 5 files | Didn't create abstraction | Create shared hook first |
+
+---
+
+## Related Documents
+
+| Document | Purpose | Timing |
+|----------|---------|--------|
+| [Pre-Implementation Checklist](./pre-implementation-checklist.md) | Questions before coding | **Before** writing code |
+| **Code Reuse Thinking Guide** (this) | Pattern recognition | During/after implementation |
+| [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md) | Data flow across layers | Complex feature planning |
+| `/check-cross-layer` command | Verification check | After implementation |
+
+---
+
+**Core Principle**: Notice patterns. Ask "should this be abstracted?" before writing similar code again.
+
+---
+
+**Language**: All documentation must be written in **English**.

package/dist/templates/markdown/structure/flows/cross-layer-thinking-guide.md.txt

@@ -0,0 +1,283 @@
+# Cross-Layer Thinking Guide
+
+> **Purpose**: A checklist to think through data flow and integration points BEFORE implementing a feature.
+
+---
+
+## Why This Guide?
+
+Most bugs happen at **layer boundaries**. This guide helps you:
+
+1. Identify all layers a feature touches
+2. Think through data transformations at each boundary
+3. Catch missing integration points before coding
+4. Document decisions for future reference
+
+---
+
+## Pre-Implementation Checklist
+
+Before writing code, answer these questions:
+
+### 1. Layer Identification
+
+**Q: Which layers does this feature touch?**
+
+| Layer | Touched? | Responsibility |
+|-------|----------|----------------|
+| UI Component | [ ] | Render, user interaction |
+| Custom Hook | [ ] | Data fetching, state logic |
+| API Route | [ ] | Request handling, validation |
+| Service Layer | [ ] | Business logic |
+| Database | [ ] | Data persistence |
+| External API | [ ] | Third-party integration |
+
+### 2. Data Flow Direction
+
+**Q: How does data flow?**
+
+```
+[ ] Read flow:  Database → Service → API → Hook → Component
+[ ] Write flow: Component → Hook → API → Service → Database
+[ ] Both ways (bidirectional)
+```
+
+### 3. Data Transformation Points
+
+**Q: Where does data format change?**
+
+| From | To | Transformation | Who handles it? |
+|------|----|----------------|-----------------|
+| Database rows | Service objects | ORM hydration | ORM (Drizzle) |
+| Service objects | API response | Serialization | API route |
+| API response | Hook data | Type casting | React Query |
+| Hook data | Component props | Selection/filter | Component |
+
+### 4. Validation Points
+
+**Q: Where is data validated?**
+
+| Point | Validation | Schema |
+|-------|------------|--------|
+| API input | Request body/params | Zod schema |
+| Service input | Business rules | Custom checks |
+| Database | Constraints | Schema constraints |
+
+### 5. Error Handling
+
+**Q: How do errors propagate?**
+
+| Layer | Error Type | Handling |
+|-------|------------|----------|
+| Database | Query error | Throw, log |
+| Service | Business error | Throw custom error |
+| API | HTTP error | Return status + message |
+| Hook | Error state | Expose to component |
+| Component | UI error | Show error message |
+
+---
+
+## Common Cross-Layer Patterns
+
+### Pattern A: CRUD Feature
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    THINK THROUGH                             │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  1. CREATE                                                   │
+│     └─ UI: What triggers creation? (button, form)           │
+│     └─ API: What's the input schema?                        │
+│     └─ DB: What tables are affected?                        │
+│     └─ Response: What does UI need back?                    │
+│                                                              │
+│  2. READ                                                     │
+│     └─ List view: What fields needed? (avoid over-fetch)    │
+│     └─ Detail view: Lazy load heavy content?                │
+│     └─ Loading: Show skeleton? Empty state?                 │
+│                                                              │
+│  3. UPDATE                                                   │
+│     └─ Optimistic UI? (update local before API responds)    │
+│     └─ Validation: Same rules as create?                    │
+│     └─ Partial update? (PATCH vs PUT)                       │
+│                                                              │
+│  4. DELETE                                                   │
+│     └─ Soft delete? (isDeleted flag)                        │
+│     └─ Cascade? (related entities)                          │
+│     └─ Confirmation required?                               │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Pattern B: Form Submission
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    THINK THROUGH                             │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  1. INPUT                                                    │
+│     └─ What fields are required vs optional?                │
+│     └─ What validations on each field?                      │
+│     └─ Real-time validation or on submit?                   │
+│                                                              │
+│  2. SUBMISSION                                               │
+│     └─ Disable button while submitting?                     │
+│     └─ Show loading indicator?                              │
+│     └─ Prevent double submission?                           │
+│                                                              │
+│  3. SUCCESS                                                  │
+│     └─ Redirect to where?                                   │
+│     └─ Show success message?                                │
+│     └─ Invalidate which queries?                            │
+│                                                              │
+│  4. ERROR                                                    │
+│     └─ Show inline errors or toast?                         │
+│     └─ Which fields keep values?                            │
+│     └─ How to retry?                                        │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Pattern C: Data List with Filters
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    THINK THROUGH                             │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  1. FILTERS                                                  │
+│     └─ Which filters are available?                         │
+│     └─ Filters in URL for shareability?                     │
+│     └─ Server-side or client-side filtering?                │
+│                                                              │
+│  2. PAGINATION                                               │
+│     └─ Page-based or cursor-based?                          │
+│     └─ Total count needed?                                  │
+│     └─ Infinite scroll or explicit pages?                   │
+│                                                              │
+│  3. SORTING                                                  │
+│     └─ Default sort order?                                  │
+│     └─ Multi-column sort?                                   │
+│     └─ Server-side or client-side?                          │
+│                                                              │
+│  4. LOADING                                                  │
+│     └─ Skeleton for initial load?                           │
+│     └─ Overlay for filter change?                           │
+│     └─ Keep previous data while loading?                    │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Layer-Specific Questions
+
+### Component Layer
+
+- [ ] What props are required vs optional?
+- [ ] What callbacks are needed? (onChange, onSubmit, onError)
+- [ ] Loading/error/empty states handled?
+
+### Hook Layer
+
+- [ ] Query key includes all dependencies?
+- [ ] Enabled condition correct?
+- [ ] Error handling defined?
+- [ ] Invalidation after mutation?
+
+### API Layer
+
+- [ ] Input schema defined?
+- [ ] Output schema defined?
+- [ ] Error responses standardized?
+- [ ] Authentication required?
+
+### Service Layer
+
+- [ ] Business validation complete?
+- [ ] Transactions for multi-table ops?
+- [ ] Errors properly typed?
+
+### Database Layer
+
+- [ ] Indexes for query patterns?
+- [ ] Foreign key constraints?
+- [ ] Soft delete vs hard delete?
+
+---
+
+## Quick Decision Tree
+
+```
+Start: New Feature
+    │
+    ├─ Touches 3+ layers?
+    │   ├─ Yes → Use this thinking guide
+    │   └─ No → Standard implementation
+    │
+    ├─ Has form submission?
+    │   ├─ Yes → Think through Pattern B
+    │   └─ No → Skip
+    │
+    ├─ Has data list?
+    │   ├─ Yes → Think through Pattern C
+    │   └─ No → Skip
+    │
+    ├─ Has CRUD operations?
+    │   ├─ Yes → Think through Pattern A
+    │   └─ No → Skip
+    │
+    └─ Done: Implementation checklist ready
+```
+
+---
+
+## Lessons from Past Bugs
+
+| Bug | Root Cause | Prevention |
+|-----|------------|------------|
+| Data missing in component | API didn't include field | Document required fields |
+| Type mismatch | API returns string, hook expects number | Use shared Zod schemas |
+| Stale UI after mutation | Forgot to invalidate query | Checklist for mutations |
+| Error not shown | Error thrown but not caught | Error boundary + hook error state |
+| Double submission | No loading state check | Disable button + loading state |
+
+---
+
+## Template: Pre-Implementation Notes
+
+Copy this template when starting a new feature:
+
+```markdown
+## Feature: [Name]
+
+### Layers Touched
+- [ ] Component
+- [ ] Hook
+- [ ] API
+- [ ] Service
+- [ ] Database
+
+### Data Flow
+[Draw ASCII diagram]
+
+### Key Decisions
+1. Validation: 
+2. Error handling: 
+3. Loading states: 
+4. Caching strategy: 
+
+### Open Questions
+- [ ] Question 1
+- [ ] Question 2
+```
+
+---
+
+**Remember**: 30 minutes of thinking saves 3 hours of debugging.
+
+---
+
+**Language**: All documentation must be written in **English**.