1{
2  "patterns": {
3    "prd_document_separation": {
4      "id": "pat-2025-01-11-001",
5      "name": "Document Separation for Complex PRDs",
6      "source": "user_feedback",
7      "confidence": 0.95,
8      "applications": 0,
9      "created": "2025-01-11",
10      "category": "prd_structure",
11      "pattern": "For non-trivial PRDs, split into 4 files with clear purposes",
12      "problem": "Single large PRD file (~500 lines) with mixed product/technical content is hard to follow",
13      "solution": {
14        "files": [
15          {
16            "name": "{name}-notes.md",
17            "purpose": "Thinking process, options analysis",
18            "audience": "Self + future reviewers"
19          },
20          {
21            "name": "{name}-task-plan.md",
22            "purpose": "Project tracking, phases, progress",
23            "audience": "PM + development lead"
24          },
25          {
26            "name": "{name}-prd.md",
27            "purpose": "Product requirements (what & why)",
28            "audience": "PM + stakeholders + developers"
29          },
30          {
31            "name": "{name}-tech.md",
32            "purpose": "Technical design (how)",
33            "audience": "Developers + architects"
34          }
35        ]
36      },
37      "quality_rules": [
38        "PRD focuses on problem, goals, scope, user flows",
39        "Tech doc focuses on API, data flow, implementation",
40        "Notes document architecture options with A/B/C analysis",
41        "Task plan has checkboxes with timestamps",
42        "PRD references tech doc, doesn't duplicate"
43      ],
44      "target_skills": ["prd-planner", "architecting-solutions"]
45    },
46    "state_monitoring_over_callbacks": {
47      "id": "pat-2025-01-11-002",
48      "name": "Direct State Monitoring vs Callbacks",
49      "source": "implementation_review",
50      "confidence": 0.90,
51      "applications": 0,
52      "created": "2025-01-11",
53      "category": "react_patterns",
54      "pattern": "Prefer direct state monitoring over callback chains for side effects",
55      "problem": "Callback chains passed through multiple layers are hard to trace and debug",
56      "solution": {
57        "anti_pattern": "useActionQueue({ onRefresh: () => { /* refresh logic */ } });",
58        "pattern": "const pendingCount = requests.length;\nconst prevPendingCount = usePrevious(pendingCount);\nuseEffect(() => {\n  if (pendingCount < prevPendingCount) {\n    triggerDataRefresh({ reason: 'completed' });\n  }\n}, [pendingCount, prevPendingCount]);"
59      },
60      "when_to_use": [
61        "State changes need to trigger side effects",
62        "Callback chain would be 3+ layers deep",
63        "Multiple components need to react to same state change"
64      ],
65      "quality_rules": [
66        "Use usePrevious to detect state changes instead of callbacks when feasible",
67        "Keep state monitoring close to where state is consumed",
68        "Use callbacks only for cross-component boundaries"
69      ],
70      "target_skills": ["debugger", "refactoring-specialist"]
71    },
72    "state_machine_over_booleans": {
73      "id": "pat-2025-01-11-003",
74      "name": "State Machine Over Boolean Flags",
75      "source": "implementation_review",
76      "confidence": 0.85,
77      "applications": 0,
78      "created": "2025-01-11",
79      "category": "async_patterns",
80      "pattern": "Use state machines for async operations with multiple phases",
81      "problem": "Simple boolean flags can't represent 'waiting to run' vs 'currently running', causing race conditions",
82      "solution": {
83        "anti_pattern": "const inFlight = false;",
84        "pattern": "enum EStatus {\n  Idle = 'idle',\n  Waiting = 'waiting',  // Scheduled but not running yet\n  Running = 'running',\n}"
85      },
86      "benefits": [
87        "Prevents race conditions (can't schedule new request while running)",
88        "Distinguishes 'waiting to run' from 'currently running'",
89        "Easier to debug and log state transitions"
90      ],
91      "quality_rules": [
92        "Use state machine for async operations with multiple phases",
93        "Prevent state transitions that don't make sense",
94        "Log state transitions for debugging"
95      ],
96      "target_skills": ["debugger", "api-designer"]
97    },
98    "measurable_success_criteria": {
99      "id": "pat-2025-01-11-004",
100      "name": "Measurable Success Criteria",
101      "source": "user_feedback",
102      "confidence": 0.90,
103      "applications": 0,
104      "created": "2025-01-11",
105      "category": "prd_quality",
106      "pattern": "Success criteria must include specific numbers/timings to enable verification",
107      "problem": "Vague success criteria like 'data refreshes' don't enable testing or verification",
108      "solution": {
109        "bad_examples": [
110          "Data refreshes after transaction",
111          "Manual refresh works",
112          "No performance regression"
113        ],
114        "good_examples": [
115          "Dashboard data refreshes within 3-5 seconds after a pending action completes",
116          "Manual refresh button triggers full refresh and shows loading state",
117          "API response time under 500ms for 95th percentile"
118        ]
119      },
120      "quality_rules": [
121        "Success criteria include specific numbers/timings",
122        "Each criterion is objectively verifiable",
123        "Performance targets have percentiles (e.g., 95th, 99th)",
124        "User-facing behavior has observable indicators"
125      ],
126      "target_skills": ["prd-planner", "architecting-solutions"]
127    },
128    "non_goals_section": {
129      "id": "pat-2025-01-11-005",
130      "name": "Non-Goals Section",
131      "source": "user_feedback",
132      "confidence": 0.90,
133      "applications": 0,
134      "created": "2025-01-11",
135      "category": "prd_structure",
136      "pattern": "Explicitly state what won't be done to prevent scope creep",
137      "problem": "Without explicit non-goals, scope creeps during implementation",
138      "solution": {
139        "structure": "## Goals\n- [Specific achievable outcomes]\n\n## Non-Goals\n- [Explicit exclusions - things that might seem related but aren't]"
140      },
141      "quality_rules": [
142        "Goals section has 3-5 focused items",
143        "Non-goals section explicitly excludes reasonable-but-out-of-scope items",
144        "Each non-goal has a brief rationale if not obvious"
145      ],
146      "target_skills": ["prd-planner", "architecting-solutions"]
147    },
148    "ui_ux_specification_granularity": {
149      "id": "pat-2025-01-11-006",
150      "name": "UI/UX Specification Granularity",
151      "source": "retrospective",
152      "confidence": 0.95,
153      "applications": 0,
154      "created": "2025-01-11",
155      "category": "ui_patterns",
156      "pattern": "UI/UX PRDs require explicit visual specifications to prevent rework",
157      "problem": "Ambiguous UI specs (position, size, spacing) cause implementation rework",
158      "solution": {
159        "required_elements": {
160          "layout_structure": ["Relative position: same row / next row / below / above", "Parent-child container relationships", "Spacing values (gap, padding, margin)"],
161          "component_specs": ["Icon/Button sizes: iconSize=\"$4\" (24px)", "Text styles: size=\"$bodyMd\", color=\"$textSubdued\"", "Component variants: size=\"small\", variant=\"tertiary\""],
162          "visual_comparison": "Before/After ASCII art showing layout change",
163          "executable_criteria": "Checklist with exact prop values"
164        },
165        "examples": {
166          "bad": "Refresh button next to amount",
167          "good": "Refresh button in same XStack as amount with gap='$3'"
168        }
169      },
170      "quality_rules": [
171        "Relative position explicitly stated (same row/next row/below/above)",
172        "Component sizes with exact values (iconSize prop or px)",
173        "Spacing values defined (gap=\"$3\", mx=\"$2\")",
174        "Before/After visual comparison included",
175        "Success criteria are executable (verify by reading code)",
176        "Mobile vs desktop differences explicitly called out"
177      ],
178      "target_skills": ["prd-planner", "architecting-solutions"]
179    },
180    "reuse_existing_infrastructure": {
181      "id": "pat-2025-01-11-007",
182      "name": "Reuse Existing Infrastructure",
183      "source": "comparison_analysis",
184      "confidence": 0.90,
185      "applications": 0,
186      "created": "2025-01-11",
187      "category": "architecture",
188      "pattern": "Always check if Context/Provider already has the data before adding new fetching",
189      "problem": "Adding duplicate data fetching creates redundant network calls and complexity",
190      "solution": {
191        "anti_pattern": "const { pendingRequests } = useActionQueue({ workspaceId, userId, client }); // Creates new polling loop!",
192        "pattern": "const { pendingRequests } = useFeatureContext(); // Shared provider already updates this"
193      },
194      "quality_checklist": [
195        "Check if Context/Provider already has the data",
196        "Verify no duplicate polling/fetching",
197        "Confirm single source of truth",
198        "Only add new fetching when lifecycle is truly independent"
199      ],
200      "benefits": ["Reduces network/background calls", "Better performance (no redundant work)", "Single source of truth", "Simpler code (fewer hooks to manage)"],
201      "target_skills": ["architecting-solutions", "api-designer", "debugger"]
202    },
203    "click_time_vs_open_time_computation": {
204      "id": "pat-2025-01-11-008",
205      "name": "Click-Time vs Open-Time Computation",
206      "source": "implementation_review",
207      "confidence": 0.85,
208      "applications": 0,
209      "created": "2025-01-11",
210      "category": "react_patterns",
211      "pattern": "For mutable state, compute at action time, not at render/init time",
212      "problem": "Open-time computation creates stale snapshots when state changes before user acts",
213      "solution": {
214        "anti_pattern": "const allIds = useMemo(() =>\n  actionableItems.filter(i => !inFlightIds.includes(i.id)),\n  [actionableItems, inFlightIds]\n); // Stale if inFlightIds changes before user clicks",
215        "pattern": "onRunAll: (ids: string[]) => Promise<void> => {\n  const freshIds = actionableItems\n    .filter(i => !inFlightIds.includes(i.id))\n    .map(i => i.id);\n  return submitBatchAction(freshIds);\n}"
216      },
217      "decision_matrix": {
218        "open_time": ["Immutable data", "Expensive computation"],
219        "click_time": ["Mutable state", "User-dependent filters"]
220      },
221      "benefits": ["State is always fresh when user acts", "No stale data issues", "Simpler reasoning about state"],
222      "target_skills": ["debugger", "api-designer"]
223    },
224    "search_before_creating_components": {
225      "id": "pat-2025-01-11-009",
226      "name": "Search Before Creating Components",
227      "source": "prud_correction",
228      "confidence": 0.90,
229      "applications": 0,
230      "created": "2025-01-11",
231      "category": "development",
232      "pattern": "ALWAYS search existing codebase before proposing new components/types",
233      "problem": "Creating duplicate components creates maintenance burden and UI inconsistency",
234      "solution": {
235        "pre_prd_search": [
236          "grep -r \"Alert\" packages/kit/src/views/ --include=\"*.tsx\"",
237          "grep -r \"IAlert\\|Alert\" packages/shared/types/ --include=\"*.ts\"",
238          "If found, read existing implementation"
239        ],
240        "decision_matrix": {
241          "existing_component_matches_ui": "Reuse",
242          "existing_component_needs_small_tweak": "Extend or wrap",
243          "existing_component_has_wrong_responsibilities": "Create new",
244          "not_sure": "Reuse first"
245        }
246      },
247      "impact": {
248        "duplicate_component": "Over-engineering, UI inconsistency",
249        "reuse": "Faster implementation, shared improvements"
250      },
251      "target_skills": ["prd-planner", "architecting-solutions", "api-designer"]
252    },
253    "spacing_and_divider_debugging": {
254      "id": "pat-2025-01-11-010",
255      "name": "Spacing and Divider Debugging",
256      "source": "bug_analysis",
257      "confidence": 0.85,
258      "applications": 0,
259      "created": "2025-01-11",
260      "category": "debugging",
261      "pattern": "When debugging spacing/divider issues, audit all spacing values systematically",
262      "problem": "Component spacing (mt, mb, py, padding) can create unintended visual separators that appear as extra lines",
263      "solution": {
264        "debugging_steps": [
265          "Search for spacing-related props in components",
266          "Check for StyleSheet.hairlineWidth usage (may render differently per platform)",
267          "Compare components that work vs components that have issues",
268          "Draw component structure to identify spacing conflicts"
269        ],
270        "audit_template": "| Element | Before | After | Unit | Notes |\\n|---------|--------|-------|------|-------|\\n| Trigger padding | `py=\"$3\"` | - | 12px | Accordion.Trigger |\\n| Header top margin | `mt=\"$3\"` | `mt=\"$0\"` | 12px → 0px | Remove this |"
271      },
272      "quality_rules": [
273        "Include ASCII diagram showing component structure",
274        "List exact spacing values with pixel conversions ($3 = 12px, $5 = 20px)",
275        "Compare working vs broken components",
276        "Note platform-specific behaviors (hairlineWidth varies)",
277        "Verify fix on all platforms (iOS, Android, Desktop, Web)"
278      ],
279      "target_skills": ["debugger"]
280    }
281  },
282  "meta": {
283    "version": "1.0.0",
284    "last_updated": "2025-01-12",
285    "total_patterns": 10,
286    "categories": ["prd_structure", "prd_quality", "react_patterns", "async_patterns", "ui_patterns", "architecture", "development", "debugging"]
287  }
288}
289