@mind-fold/open-flow 0.1.17 → 0.2.2

package/dist/templates/markdown/structure/flows/index.md.txt

@@ -0,0 +1,133 @@
+# Cross-Layer Flow Specifications
+
+> **Purpose**: Document data flows that span multiple layers and thinking guides to prevent common bugs.
+
+---
+
+## Why This Directory?
+
+Most bugs happen at **layer boundaries**, not within layers. This directory provides:
+
+1. **Thinking guides** - Checklists to prevent bugs before they happen
+2. **Flow specs** - Documentation of cross-layer data flows
+3. **Templates** - For creating new flow documentation
+
+---
+
+## How to Use This Directory
+
+```
+Before writing ANY code
+    │
+    ├─ Read: Pre-Implementation Checklist
+    │   └─ "Will this constant be used elsewhere?"
+    │   └─ "Does this pattern already exist?"
+    │
+    ├─ If feature spans 3+ layers
+    │   └─ Read: Cross-Layer Thinking Guide
+    │   └─ Consider creating a Flow Spec
+    │
+    └─ During/After implementation
+        └─ Reference: Code Reuse Thinking Guide
+        └─ Run: /check-cross-layer command
+```
+
+---
+
+## Guides
+
+### Pre-Implementation (Read First!)
+
+| Document | Purpose | When to Read |
+|----------|---------|--------------|
+| [Pre-Implementation Checklist](./pre-implementation-checklist.md) | **Start here!** Questions before coding | Before writing ANY code |
+
+### During Implementation
+
+| Document | Purpose | When to Read |
+|----------|---------|--------------|
+| [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md) | Data flow across layers | Complex features spanning 3+ layers |
+| [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md) | Pattern recognition, abstraction | When implementing logic/components |
+| [Flow Spec Template](./spec-flow-template.md) | Template for new flow docs | When documenting a new flow |
+
+---
+
+## When to Create a Flow Spec
+
+Create a flow spec when a feature:
+
+- [ ] Spans 3+ layers (e.g., API → Service → Component → Hook)
+- [ ] Has transformation points where data format changes
+- [ ] Has multiple consumers with different requirements
+- [ ] Involves state that passes through multiple components
+- [ ] Has caused bugs due to missing data or wrong format
+
+---
+
+## Quick Reference: Common Cross-Layer Patterns
+
+### Pattern 1: API → Service → Component
+
+```
+API Route              # Validate input, call service
+    │
+    ▼
+Service Layer          # Business logic, database
+    │
+    ▼
+Response               # Format for client
+    │
+    ▼
+React Query Hook       # Cache, loading states
+    │
+    ▼
+Component              # Render UI
+```
+
+**Common Mistake**: Service returns different format than hook expects.
+
+### Pattern 2: User Action → State → API → Refetch
+
+```
+User clicks button        # UI Layer
+    │
+    ▼
+Call mutation hook        # React Query mutation
+    │
+    ▼
+API Request               # POST/PATCH/DELETE
+    │
+    ▼
+Invalidate queries        # Trigger refetch
+    │
+    ▼
+UI updates                # New data rendered
+```
+
+**Common Mistake**: Forgetting to invalidate related queries.
+
+---
+
+## Triggers for Using These Guides
+
+| Trigger | Action |
+|---------|--------|
+| About to write any code | Read Pre-Implementation Checklist |
+| Feature spans 3+ layers | Read Cross-Layer Thinking Guide |
+| Creating a new utility/constant | Check Code Reuse Guide |
+| Just finished batch modifications | Run /check-cross-layer |
+| Feels like you've seen similar code | **STOP** and search first |
+
+---
+
+## Integration with Commands
+
+| Command | Purpose | Timing |
+|---------|---------|--------|
+| `/check-cross-layer` | Verify changes after implementation | After coding |
+| `/finish-work` | Pre-commit checklist | Before commit |
+| `/break-loop` | Post-debug analysis | After fixing bugs |
+
+---
+
+**Language**: All documentation must be written in **English**.

package/dist/templates/markdown/structure/flows/pre-implementation-checklist.md.txt

@@ -0,0 +1,182 @@
+# Pre-Implementation Checklist
+
+> **Purpose**: Ask the right questions **before** writing code to avoid common architectural mistakes.
+
+---
+
+## Why This Checklist?
+
+Most code quality issues aren't caught during implementation—they're **designed in** from the start:
+
+| Problem | Root Cause | Cost |
+|---------|------------|------|
+| Constants duplicated across 5 files | Didn't ask "will this be used elsewhere?" | Refactoring + testing |
+| Same logic repeated in multiple hooks | Didn't ask "does this pattern exist?" | Creating abstraction later |
+| Cross-layer type mismatches | Didn't ask "who else consumes this?" | Debugging + fixing |
+
+**This checklist catches these issues before they become code.**
+
+---
+
+## The Checklist
+
+### 1. Constants & Configuration
+
+Before adding any constant or config value:
+
+- [ ] **Cross-layer usage?** Will this value be used in both frontend and backend?
+  - If yes → Put in shared constants file
+  - Example: Batch size used by backend sync AND frontend threshold check
+
+- [ ] **Multiple consumers?** Will this value be used in 2+ files within the same layer?
+  - If yes → Put in a shared constants file for that layer
+  - Example: Don't define `DEBOUNCE_MS = 2000` in each hook file
+
+- [ ] **Magic number?** Is this a hardcoded value that could change?
+  - If yes → Extract to named constant with comment explaining why
+  - Example: `BATCH_SIZE: 15  // API limit constraint`
+
+### 2. Logic & Patterns
+
+Before implementing any logic:
+
+- [ ] **Pattern exists?** Search for similar patterns in the codebase first
+  ```bash
+  # Example: Before implementing debounced sync
+  grep -r "setTimeout.*sync" src/
+  grep -r "debounce" src/
+  ```
+
+- [ ] **Will repeat?** Will this exact logic be needed in 2+ places?
+  - If yes → Create a shared hook/utility **first**, then use it
+  - Don't copy-paste and plan to refactor later
+
+- [ ] **Callback pattern?** Does the logic need optional callbacks (onStart, onComplete, onError)?
+  - If yes → Design the abstraction with callback support from the start
+
+### 3. Types & Interfaces
+
+Before defining types:
+
+- [ ] **Cross-layer type?** Is this type used across API boundary?
+  - If yes → Define in shared types location
+  - Never duplicate type definitions between frontend and backend
+
+- [ ] **Existing type?** Does a similar type already exist?
+  - Search before creating: `grep -r "interface.*YourTypeName" src/`
+
+### 4. UI Components
+
+Before creating UI components:
+
+- [ ] **Visual-logic consistency?** If there's already a visual distinction (icon, color, label) for a concept, does your logic match?
+  - Example: If items show priority icons in a specific order, sorting logic should use the same order
+
+- [ ] **State lifecycle?** Will this component unmount during normal user flow?
+  - If yes → Consider where state should persist (parent, context, store)
+
+---
+
+## Quick Decision Tree
+
+```
+Adding a value/constant?
+├── Used in frontend AND backend? → Shared constants
+├── Used in 2+ files in same layer? → Layer-specific shared constants
+└── Single file only? → Local constant is fine
+
+Adding logic/behavior?
+├── Similar pattern exists? → Extend or reuse existing
+├── Will be used in 2+ places? → Create shared hook/utility first
+└── Single use only? → Implement directly (but document pattern)
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+### ❌ Copy-Paste-Modify
+
+```typescript
+// DON'T: Same logic in multiple files
+// file1.ts, file2.ts, file3.ts...
+const DEBOUNCE_MS = 2000;
+const MAX_PENDING = 15;
+const triggerSync = useCallback(() => {
+  // 20 lines of identical logic
+}, []);
+```
+
+### ✅ Shared Abstraction
+
+```typescript
+// DO: Single source of truth
+// useSyncTrigger.ts
+import { SYNC_CONSTANTS } from "@shared/constants";
+export function useSyncTrigger(options) { /* logic once */ }
+
+// file1.ts - one line instead of 20+
+const triggerSync = useSyncTrigger({ workspaceId });
+```
+
+### ❌ Local Constant Aliases
+
+```typescript
+// DON'T: Create local aliases for imported constants
+import { CONSTANTS } from "@shared/constants";
+const DEBOUNCE_MS = CONSTANTS.DEBOUNCE_MS;  // Unnecessary!
+```
+
+### ✅ Direct Usage
+
+```typescript
+// DO: Use imported constants directly
+import { CONSTANTS } from "@shared/constants";
+setTimeout(fn, CONSTANTS.DEBOUNCE_MS);
+```
+
+---
+
+## When to Use This Checklist
+
+| Trigger | Action |
+|---------|--------|
+| About to add a constant | Run through Section 1 |
+| About to implement logic | Run through Section 2 |
+| About to define a type | Run through Section 3 |
+| About to create a component | Run through Section 4 |
+| Feels like you've seen similar code before | **STOP** and search first |
+
+---
+
+## Relationship to Other Guides
+
+| Guide | Focus | Timing |
+|-------|-------|--------|
+| **Pre-Implementation Checklist** (this) | Questions before coding | Before writing code |
+| [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md) | Patterns and abstractions | 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 (safety net) |
+
+**Ideal workflow:**
+1. Read this checklist before coding
+2. Reference Code Reuse guide for abstraction patterns
+3. Run `/check-cross-layer` after implementation as safety net
+
+---
+
+## Lessons Learned
+
+| Issue | Lesson |
+|-------|--------|
+| Same constant duplicated in 5+ hooks | Always ask "will this constant be used elsewhere?" before defining |
+| Same logic copied multiple times | If logic will repeat, create abstraction **before** first use |
+| Created local aliases for imported constants | Never create local aliases—use imported constants directly |
+
+---
+
+**Core Principle**: 5 minutes of checklist thinking saves 50 minutes of refactoring.
+
+---
+
+**Language**: All documentation must be written in **English**.

package/dist/templates/markdown/structure/flows/spec-flow-template.md.txt

@@ -0,0 +1,145 @@
+# Flow Spec: [Feature Name]
+
+> Template for documenting cross-layer data flows
+
+---
+
+## Overview
+
+**Feature**: [Brief description]
+**Layers**: [List layers involved]
+**Last Updated**: [Date]
+
+---
+
+## Data Flow Diagram
+
+```
+[Source]
+    │
+    ▼
+[Layer 1] ─────────────────────────────┐
+    │                                   │
+    │  Data: { field1, field2 }        │
+    │  Transform: none                  │
+    │                                   │
+    ▼                                   │
+[Layer 2] ─────────────────────────────┤
+    │                                   │
+    │  Data: { field1, field2, extra } │
+    │  Transform: add computed field    │
+    │                                   │
+    ▼                                   │
+[Layer 3] ─────────────────────────────┘
+    │
+    ▼
+[Consumer]
+```
+
+---
+
+## Layer Details
+
+### Layer 1: [Name]
+
+**File**: `path/to/file.ts`
+
+**Input**:
+```typescript
+{
+  field1: string;
+  field2: number;
+}
+```
+
+**Output**:
+```typescript
+{
+  field1: string;
+  field2: number;
+}
+```
+
+**Transformation**: None (pass-through)
+
+**Error Handling**: 
+- Validation errors → 400 response
+- Not found → 404 response
+
+---
+
+### Layer 2: [Name]
+
+**File**: `path/to/file.ts`
+
+**Input**: Output from Layer 1
+
+**Output**:
+```typescript
+{
+  field1: string;
+  field2: number;
+  computed: string;  // Added
+}
+```
+
+**Transformation**: 
+- Adds `computed` field based on `field1` and `field2`
+
+**Error Handling**:
+- Business logic errors → throw CustomError
+
+---
+
+### Layer 3: [Name]
+
+**File**: `path/to/file.ts`
+
+**Input**: Output from Layer 2
+
+**Output**: Same as input (display only)
+
+**Transformation**: None
+
+**Error Handling**:
+- Show error message to user
+- Allow retry
+
+---
+
+## Edge Cases
+
+| Scenario | Expected Behavior | Layer Handling |
+|----------|-------------------|----------------|
+| Empty data | Show empty state | Component |
+| Network error | Show error + retry | Hook |
+| Validation error | Show field errors | Component |
+| Not found | Redirect to 404 | API |
+
+---
+
+## Testing Checklist
+
+- [ ] Happy path: All layers work together
+- [ ] Error at Layer 1: Properly propagates
+- [ ] Error at Layer 2: Properly propagates
+- [ ] Empty data: Handled correctly
+- [ ] Loading state: Displayed correctly
+
+---
+
+## Change Log
+
+| Date | Change | Affected Layers |
+|------|--------|-----------------|
+| YYYY-MM-DD | Initial spec | All |
+
+---
+
+## Notes
+
+[Any additional context, decisions, or warnings]
+
+---
+
+**Language**: All documentation must be written in **English**.