@fro.bot/systematic 3.26.2 → 3.26.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -17,9 +17,11 @@ allowed-tools:
17
17
 
18
18
  This skill captures problem solutions immediately after confirmation, creating structured documentation that serves as a searchable knowledge base for future sessions.
19
19
 
20
- **Organization:** Single-file architecture - each problem documented as one markdown file in its symptom category directory (e.g., `docs/solutions/performance-issues/n-plus-one-briefs.md`). Files use YAML frontmatter for metadata and searchability.
20
+ **Organization:** Single-file architecture - each learning documented as one markdown file in the category directory its `problem_type` maps to (e.g., `docs/solutions/performance-issues/n-plus-one-report-queries.md`). Files use YAML frontmatter for metadata and searchability.
21
21
 
22
- **Prerequisites:** The problem has been solved and the solution has been verified working. Do not document in-progress investigations as finalized solutions.
22
+ **Two tracks:** The `problem_type` decides the track. The **bug track** documents a defect that was diagnosed and fixed, and requires `symptoms`, `root_cause` and `resolution_type`. The **knowledge track** documents a practice, pattern, convention or workflow decision, and needs none of those. The track lists live in [references/schema.yaml](./references/schema.yaml).
23
+
24
+ **Prerequisites:** The problem has been solved and the solution has been verified working, or the guidance has been confirmed. Do not document in-progress investigations as finalized solutions.
23
25
 
24
26
  ---
25
27
 
@@ -57,32 +59,42 @@ This skill captures problem solutions immediately after confirmation, creating s
57
59
  <step number="2" required="true" depends_on="1">
58
60
  ### Step 2: Gather Context
59
61
 
60
- Extract from conversation history:
62
+ Decide the track first: a fixed defect is the bug track, and a practice or decision worth keeping is the knowledge track. Then extract from conversation history:
63
+
64
+ **Required for both tracks:**
65
+
66
+ - **Module name**: Which module or area the learning applies to
67
+ - **Prevention or guidance**: How to avoid the problem, or what to do instead
61
68
 
62
- **Required information:**
69
+ **Bug track:**
63
70
 
64
- - **Module name**: Which module or component had the problem
65
71
  - **Symptom**: Observable error/behavior (exact error messages)
66
72
  - **Investigation attempts**: What didn't work and why
67
73
  - **Root cause**: Technical explanation of actual problem
68
74
  - **Solution**: What fixed it (code/config changes)
69
- - **Prevention**: How to avoid in future
70
75
 
71
- **Environment details:**
76
+ **Knowledge track:**
77
+
78
+ - **Context**: The situation, gap or friction that prompted the guidance
79
+ - **Guidance**: The practice, pattern or recommendation
80
+ - **Why it matters**: Rationale and impact
81
+ - **When it applies**: Conditions where the guidance holds
82
+
83
+ **Environment details (optional):**
72
84
 
73
- - Rails version
74
- - Stage (0-6 or post-implementation)
85
+ - Runtime, framework or toolchain versions
75
86
  - OS version
76
87
  - File/line references
77
88
 
78
- **BLOCKING REQUIREMENT:** If critical context is missing (module name, exact error, stage, or resolution steps), ask user and WAIT for response before proceeding to Step 3:
89
+ **BLOCKING REQUIREMENT:** If critical context is missing, ask the user and WAIT for response before proceeding to Step 3. Bug track needs the module name, the exact error or symptom, and the resolution steps. Knowledge track needs the module name, the guidance, and when it applies:
79
90
 
80
91
  ```
81
92
  I need a few details to document this properly:
82
93
 
83
- 1. Which module had this issue? [ModuleName]
84
- 2. What was the exact error message or symptom?
85
- 3. What stage were you in? (0-6 or post-implementation)
94
+ 1. Which module or area is this about? [ModuleName]
95
+ 2. Bug track: what was the exact error message or symptom?
96
+ Knowledge track: what is the guidance, and when does it apply?
97
+ 3. Bug track only: what fixed it?
86
98
 
87
99
  [Continue after user provides details]
88
100
  ```
@@ -126,7 +138,9 @@ Proceed directly to Step 4 (no user interaction needed).
126
138
  <step number="4" required="true" depends_on="2">
127
139
  ### Step 4: Generate Filename
128
140
 
129
- Format: `[sanitized-symptom]-[module]-[YYYYMMDD].md`
141
+ Format: `[sanitized-slug]-[YYYY-MM-DD].md`
142
+
143
+ The slug is the symptom for bug-track docs. Knowledge-track docs have no symptom, so the slug is a short sanitized title of the guidance.
130
144
 
131
145
  **Sanitization rules:**
132
146
 
@@ -137,9 +151,10 @@ Format: `[sanitized-symptom]-[module]-[YYYYMMDD].md`
137
151
 
138
152
  **Examples:**
139
153
 
140
- - `missing-include-BriefSystem-20251110.md`
141
- - `parameter-not-saving-state-EmailProcessing-20251110.md`
142
- - `webview-crash-on-resize-Assistant-20251110.md`
154
+ - `n-plus-one-report-generation-2025-11-10.md` (bug track)
155
+ - `parameter-not-saving-state-2025-11-10.md` (bug track)
156
+ - `webview-crash-on-resize-2025-11-10.md` (bug track)
157
+ - `prefer-explicit-request-timeouts-2025-11-10.md` (knowledge track)
143
158
  </step>
144
159
 
145
160
  <step number="5" required="true" depends_on="4" blocking="true">
@@ -150,7 +165,11 @@ Format: `[sanitized-symptom]-[module]-[YYYYMMDD].md`
150
165
  <validation_gate name="yaml-schema" blocking="true">
151
166
 
152
167
  **Validate against schema:**
153
- Load `schema.yaml` and classify the problem against the enum values defined in [yaml-schema.md](./references/yaml-schema.md). Ensure all required fields are present and match allowed values exactly.
168
+ Load [references/schema.yaml](./references/schema.yaml) and classify the problem against the enum values defined there and summarized in [yaml-schema.md](./references/yaml-schema.md). Ensure all required fields are present and match allowed values exactly.
169
+
170
+ - Required for both tracks: `module`, `date`, `problem_type`, `component`, `severity`.
171
+ - Required for the bug track only: `symptoms` (1-5 items), `root_cause`, `resolution_type`. A knowledge-track doc may omit all three.
172
+ - Offer and write only the `values` lists. A value under `legacy_values` is accepted when an existing doc already carries it, and is never chosen for a new doc.
154
173
 
155
174
  **BLOCK if validation fails:**
156
175
 
@@ -160,12 +179,12 @@ Load `schema.yaml` and classify the problem against the enum values defined in [
160
179
  Errors:
161
180
  - problem_type: must be one of schema enums, got "compilation_error"
162
181
  - severity: must be one of [critical, high, medium, low], got "invalid"
163
- - symptoms: must be array with 1-5 items, got string
182
+ - symptoms (bug track): must be array with 1-5 items, got string
164
183
 
165
184
  Please provide corrected values.
166
185
  ```
167
186
 
168
- **GATE ENFORCEMENT:** Do NOT proceed to Step 6 (Create Documentation) until YAML frontmatter passes all validation rules defined in `schema.yaml`.
187
+ **GATE ENFORCEMENT:** Do NOT proceed to Step 6 (Create Documentation) until YAML frontmatter passes all validation rules defined in `references/schema.yaml`.
169
188
 
170
189
  </validation_gate>
171
190
  </step>
@@ -173,9 +192,9 @@ Please provide corrected values.
173
192
  <step number="6" required="true" depends_on="5">
174
193
  ### Step 6: Create Documentation
175
194
 
176
- **Determine category from problem_type:** Use the category mapping defined in [yaml-schema.md](./references/yaml-schema.md) (lines 49-61).
195
+ **Determine category from problem_type:** Use the Category Mapping section of [yaml-schema.md](./references/yaml-schema.md). The narrow knowledge types (`architecture_pattern`, `design_pattern`, `tooling_decision`, `convention`) share `best-practices/` with `best_practice`.
177
196
 
178
- **Create documentation file:**
197
+ **Create documentation file:** The directory is created on first use, so no category directory needs to exist beforehand.
179
198
 
180
199
  ```bash
181
200
  PROBLEM_TYPE="[from validated YAML]"
@@ -183,10 +202,10 @@ CATEGORY="[mapped from problem_type]"
183
202
  FILENAME="[generated-filename].md"
184
203
  DOC_PATH="docs/solutions/${CATEGORY}/${FILENAME}"
185
204
 
186
- # Create directory if needed
205
+ # Create directory on first use
187
206
  mkdir -p "docs/solutions/${CATEGORY}"
188
207
 
189
- # Write documentation using template from assets/resolution-template.md
208
+ # Write documentation using the template for the track in assets/resolution-template.md
190
209
  # (Content populated with Step 2 context and validated YAML frontmatter)
191
210
  ```
192
211
 
@@ -194,11 +213,11 @@ mkdir -p "docs/solutions/${CATEGORY}"
194
213
  - Single file in category directory
195
214
  - Enum validation ensures consistent categorization
196
215
 
197
- **Create documentation:** Populate the structure from `assets/resolution-template.md` with context gathered in Step 2 and validated YAML frontmatter from Step 5.
216
+ **Create documentation:** Populate the Bug Track or Knowledge Track template from `assets/resolution-template.md` with context gathered in Step 2 and validated YAML frontmatter from Step 5.
198
217
  </step>
199
218
 
200
219
  <step number="7" required="false" depends_on="6">
201
- ### Step 7: Cross-Reference & Critical Pattern Detection
220
+ ### Step 7: Cross-Reference
202
221
 
203
222
  If similar issues found in Step 3:
204
223
 
@@ -211,45 +230,6 @@ echo "- See also: [$FILENAME]($REAL_FILE)" >> [similar-doc.md]
211
230
 
212
231
  **Update new doc:**
213
232
  Already includes cross-reference from Step 6.
214
-
215
- **Update patterns if applicable:**
216
-
217
- If this represents a common pattern (3+ similar issues):
218
-
219
- ```bash
220
- # Add to docs/solutions/patterns/common-solutions.md
221
- cat >> docs/solutions/patterns/common-solutions.md << 'EOF'
222
-
223
- ## [Pattern Name]
224
-
225
- **Common symptom:** [Description]
226
- **Root cause:** [Technical explanation]
227
- **Solution pattern:** [General approach]
228
-
229
- **Examples:**
230
- - [Link to doc 1]
231
- - [Link to doc 2]
232
- - [Link to doc 3]
233
- EOF
234
- ```
235
-
236
- **Critical Pattern Detection (Optional Proactive Suggestion):**
237
-
238
- If this issue has automatic indicators suggesting it might be critical:
239
- - Severity: `critical` in YAML
240
- - Affects multiple modules OR foundational stage (Stage 2 or 3)
241
- - Non-obvious solution
242
-
243
- Then in the decision menu (Step 8), add a note:
244
- ```
245
- 💡 This might be worth adding to Required Reading (Option 2)
246
- ```
247
-
248
- But **NEVER auto-promote**. User decides via decision menu (Option 2).
249
-
250
- **Template for critical pattern addition:**
251
-
252
- When user selects Option 2 (Add to Required Reading), use the template from `assets/critical-pattern-template.md` to structure the pattern entry. Number it sequentially based on existing patterns in `docs/solutions/patterns/critical-patterns.md`.
253
233
  </step>
254
234
 
255
235
  </critical_sequence>
@@ -270,12 +250,10 @@ File created:
270
250
 
271
251
  What's next?
272
252
  1. Continue workflow (recommended)
273
- 2. Add to Required Reading - Promote to critical patterns (critical-patterns.md)
274
- 3. Link related issues - Connect to similar problems
275
- 4. Add to existing skill - Add to a learning skill (e.g., hotwire-native)
276
- 5. Create new skill - Extract into new learning skill
277
- 6. View documentation - See what was captured
278
- 7. Other
253
+ 2. Link related issues - Connect to similar problems
254
+ 3. Create new skill - Extract into new learning skill
255
+ 4. View documentation - See what was captured
256
+ 5. Other
279
257
  ```
280
258
 
281
259
  **Handle responses:**
@@ -285,57 +263,29 @@ What's next?
285
263
  - Return to calling skill/workflow
286
264
  - Documentation is complete
287
265
 
288
- **Option 2: Add to Required Reading** ⭐ PRIMARY PATH FOR CRITICAL PATTERNS
289
-
290
- User selects this when:
291
- - System made this mistake multiple times across different modules
292
- - Solution is non-obvious but must be followed every time
293
- - Foundational requirement (Rails, Rails API, threading, etc.)
294
-
295
- Action:
296
- 1. Extract pattern from the documentation
297
- 2. Format as ❌ WRONG vs ✅ CORRECT with code examples
298
- 3. Add to `docs/solutions/patterns/critical-patterns.md`
299
- 4. Add cross-reference back to this doc
300
- 5. Confirm: "✓ Added to Required Reading. All subagents will see this pattern before code generation."
301
-
302
- **Option 3: Link related issues**
266
+ **Option 2: Link related issues**
303
267
 
304
268
  - Prompt: "Which doc to link? (provide filename or describe)"
305
269
  - Search docs/solutions/ for the doc
306
270
  - Add cross-reference to both docs
307
271
  - Confirm: "✓ Cross-reference added"
308
272
 
309
- **Option 4: Add to existing skill**
310
-
311
- User selects this when the documented solution relates to an existing learning skill:
312
-
313
- Action:
314
- 1. Prompt: "Which skill? (hotwire-native, etc.)"
315
- 2. Determine which reference file to update (resources.md, patterns.md, or examples.md)
316
- 3. Add link and brief description to appropriate section
317
- 4. Confirm: "✓ Added to [skill-name] skill in [file]"
318
-
319
- Example: For Hotwire Native Tailwind variants solution:
320
- - Add to `hotwire-native/references/resources.md` under "Project-Specific Resources"
321
- - Add to `hotwire-native/references/examples.md` with link to solution doc
322
-
323
- **Option 5: Create new skill**
273
+ **Option 3: Create new skill**
324
274
 
325
275
  User selects this when the solution represents the start of a new learning domain:
326
276
 
327
277
  Action:
328
- 1. Prompt: "What should the new skill be called? (e.g., stripe-billing, email-processing)"
278
+ 1. Prompt: "What should the new skill be called? (e.g., release-automation, api-versioning)"
329
279
  2. Run `python3 .opencode/skills/skill-creator/scripts/init_skill.py [skill-name]`
330
280
  3. Create initial reference files with this solution as first example
331
281
  4. Confirm: "✓ Created new [skill-name] skill with this solution as first example"
332
282
 
333
- **Option 6: View documentation**
283
+ **Option 4: View documentation**
334
284
 
335
285
  - Display the created documentation
336
286
  - Present decision menu again
337
287
 
338
- **Option 7: Other**
288
+ **Option 5: Other**
339
289
 
340
290
  - Ask what they'd like to do
341
291
 
@@ -370,7 +320,7 @@ Documentation is successful when ALL of the following are true:
370
320
 
371
321
  - ✅ YAML frontmatter validated (all required fields, correct formats)
372
322
  - ✅ File created in docs/solutions/[category]/[filename].md
373
- - ✅ Enum values match schema.yaml exactly
323
+ - ✅ Enum values match references/schema.yaml exactly, offered `values` only
374
324
  - ✅ Code examples included in solution section
375
325
  - ✅ Cross-references added if related issues found
376
326
  - ✅ User presented with decision menu and action confirmed
@@ -409,7 +359,7 @@ Documentation is successful when ALL of the following are true:
409
359
 
410
360
  **MUST do:**
411
361
  - Validate YAML frontmatter (BLOCK if invalid per Step 5 validation gate)
412
- - Extract exact error messages from conversation
362
+ - Extract exact error messages from conversation (bug track)
413
363
  - Include code examples in solution section
414
364
  - Create directories before writing files (`mkdir -p`)
415
365
  - Ask user and WAIT if critical context missing
@@ -418,6 +368,7 @@ Documentation is successful when ALL of the following are true:
418
368
  - Skip YAML validation (validation gate is blocking)
419
369
  - Use vague descriptions (not searchable)
420
370
  - Omit code examples or cross-references
371
+ - Require `symptoms` or an error message for a knowledge-track doc
421
372
 
422
373
  ---
423
374
 
@@ -460,30 +411,30 @@ Documentation is successful when ALL of the following are true:
460
411
  **Skill activates:**
461
412
 
462
413
  1. **Detect confirmation:** "That worked!" triggers auto-invoke
463
- 2. **Gather context:**
464
- - Module: Brief System
465
- - Symptom: Brief generation taking >5 seconds, N+1 query when loading email threads
414
+ 2. **Gather context (bug track):**
415
+ - Module: Report Service
416
+ - Symptom: Report generation taking >5 seconds, N+1 query when loading comment threads
466
417
  - Failed attempts: Added pagination (didn't help), checked background job performance
467
- - Solution: Added eager loading with `includes(:emails)` on Brief model
468
- - Root cause: Missing eager loading causing separate database query per email thread
418
+ - Solution: Loaded the comments for all reports in one eager-loaded query
419
+ - Root cause: Missing eager loading causing a separate database query per comment thread
469
420
  3. **Check existing:** No similar issue found
470
- 4. **Generate filename:** `n-plus-one-brief-generation-BriefSystem-20251110.md`
421
+ 4. **Generate filename:** `n-plus-one-report-generation-2025-11-10.md`
471
422
  5. **Validate YAML:**
472
423
  ```yaml
473
- module: Brief System
424
+ module: Report Service
474
425
  date: 2025-11-10
475
426
  problem_type: performance_issue
476
- component: rails_model
427
+ component: backend
477
428
  symptoms:
478
- - "N+1 query when loading email threads"
479
- - "Brief generation taking >5 seconds"
429
+ - "N+1 query when loading comment threads"
430
+ - "Report generation taking >5 seconds"
480
431
  root_cause: missing_include
481
432
  severity: high
482
433
  tags: [n-plus-one, eager-loading, performance]
483
434
  ```
484
435
  ✅ Valid
485
436
  6. **Create documentation:**
486
- - `docs/solutions/performance-issues/n-plus-one-brief-generation-BriefSystem-20251110.md`
437
+ - `docs/solutions/performance-issues/n-plus-one-report-generation-2025-11-10.md`
487
438
  7. **Cross-reference:** None needed (no similar issues)
488
439
 
489
440
  **Output:**
@@ -492,18 +443,18 @@ Documentation is successful when ALL of the following are true:
492
443
  ✓ Solution documented
493
444
 
494
445
  File created:
495
- - docs/solutions/performance-issues/n-plus-one-brief-generation-BriefSystem-20251110.md
446
+ - docs/solutions/performance-issues/n-plus-one-report-generation-2025-11-10.md
496
447
 
497
448
  What's next?
498
449
  1. Continue workflow (recommended)
499
- 2. Add to Required Reading - Promote to critical patterns (critical-patterns.md)
500
- 3. Link related issues - Connect to similar problems
501
- 4. Add to existing skill - Add to a learning skill (e.g., hotwire-native)
502
- 5. Create new skill - Extract into new learning skill
503
- 6. View documentation - See what was captured
504
- 7. Other
450
+ 2. Link related issues - Connect to similar problems
451
+ 3. Create new skill - Extract into new learning skill
452
+ 4. View documentation - See what was captured
453
+ 5. Other
505
454
  ```
506
455
 
456
+ **Knowledge-track variant:** For "we should always set explicit request timeouts", the same flow asks only for the module, the guidance and when it applies. The frontmatter carries `problem_type: convention` and no `symptoms`, the file goes to `docs/solutions/best-practices/`, and the directory is created if it does not exist yet.
457
+
507
458
  ---
508
459
 
509
460
  ## Future Enhancements
@@ -1,95 +1,92 @@
1
+ # Resolution Templates
2
+
3
+ Choose the template matching the problem_type track (see `references/schema.yaml`).
4
+
5
+ **Citing code:** write a repo-relative path with the line or range (`<file>:<line>` or `<file>:<start>-<end>`), never a bare file name, and put the backticked symbol it points at in the same sentence. Link a tag or commit for code outside the repo or deleted code. Write placeholders such as `<file>:<line>` in examples. The content-integrity gate checks citations in `docs/solutions/`.
6
+
7
+ ---
8
+
9
+ ## Bug Track Template
10
+
11
+ Use for: `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, `logic_error`
12
+
13
+ ```markdown
1
14
  ---
2
- module: [Module name or "System" for system-wide]
15
+ title: [Clear problem title]
3
16
  date: [YYYY-MM-DD]
4
- problem_type: [build_error|test_failure|runtime_error|performance_issue|database_issue|security_issue|ui_bug|integration_issue|logic_error]
5
- component: [rails_model|rails_controller|rails_view|service_object|background_job|database|frontend_stimulus|hotwire_turbo|email_processing|brief_system|assistant|authentication|payments]
17
+ category: [directory name under docs/solutions/, e.g. best-practices]
18
+ module: [Module or area]
19
+ problem_type: [schema enum]
20
+ component: [schema enum]
6
21
  symptoms:
7
- - [Observable symptom 1 - specific error message or behavior]
8
- - [Observable symptom 2 - what user actually saw/experienced]
9
- root_cause: [missing_association|missing_include|missing_index|wrong_api|scope_issue|thread_violation|async_timing|memory_leak|config_error|logic_error|test_isolation|missing_validation|missing_permission]
10
- rails_version: [7.1.2 - optional]
11
- resolution_type: [code_fix|migration|config_change|test_fix|dependency_update|environment_setup]
12
- severity: [critical|high|medium|low]
13
- tags: [keyword1, keyword2, keyword3]
22
+ - [Observable symptom 1]
23
+ root_cause: [schema enum]
24
+ resolution_type: [schema enum]
25
+ severity: [schema enum]
26
+ tags: [keyword-one, keyword-two]
14
27
  ---
15
28
 
16
- # Troubleshooting: [Clear Problem Title]
29
+ # [Clear problem title]
17
30
 
18
31
  ## Problem
19
- [1-2 sentence clear description of the issue and what the user experienced]
20
-
21
- ## Environment
22
- - Module: [Name or "System-wide"]
23
- - Rails Version: [e.g., 7.1.2]
24
- - Affected Component: [e.g., "Email Processing model", "Brief System service", "Authentication controller"]
25
- - Date: [YYYY-MM-DD when this was solved]
32
+ [1-2 sentence description of the issue and user-visible impact]
26
33
 
27
34
  ## Symptoms
28
- - [Observable symptom 1 - what the user saw/experienced]
29
- - [Observable symptom 2 - error messages, visual issues, unexpected behavior]
30
- - [Continue as needed - be specific]
35
+ - [Observable symptom or error]
31
36
 
32
37
  ## What Didn't Work
33
-
34
- **Attempted Solution 1:** [Description of what was tried]
35
- - **Why it failed:** [Technical reason this didn't solve the problem]
36
-
37
- **Attempted Solution 2:** [Description of second attempt]
38
- - **Why it failed:** [Technical reason]
39
-
40
- [Continue for all significant attempts that DIDN'T work]
41
-
42
- [If nothing else was attempted first, write:]
43
- **Direct solution:** The problem was identified and fixed on the first attempt.
38
+ - [Attempted fix and why it failed]
44
39
 
45
40
  ## Solution
41
+ [The fix that worked, including code snippets when useful]
46
42
 
47
- [The actual fix that worked - provide specific details]
48
-
49
- [Cite code as a repo-relative `<file>:<line>` or `<file>:<start>-<end>`, with the backticked symbol in the same sentence. Link a tag or commit for code outside the repo or deleted code. The content-integrity gate checks these citations.]
43
+ ## Why This Works
44
+ [Root cause explanation and why the fix addresses it]
50
45
 
51
- **Code changes** (if applicable):
52
- ```ruby
53
- # Before (broken):
54
- [Show the problematic code]
46
+ ## Prevention
47
+ - [Concrete practice, test, or guardrail]
55
48
 
56
- # After (fixed):
57
- [Show the corrected code with explanation]
49
+ ## Related Issues
50
+ - [Related docs or issues, if any]
58
51
  ```
59
52
 
60
- **Database migration** (if applicable):
61
- ```ruby
62
- # Migration change:
63
- [Show what was changed in the migration]
64
- ```
53
+ ---
65
54
 
66
- **Commands run** (if applicable):
67
- ```bash
68
- # Steps taken to fix:
69
- [Commands or actions]
70
- ```
55
+ ## Knowledge Track Template
71
56
 
72
- ## Why This Works
57
+ Use for: `best_practice`, `documentation_gap`, `workflow_issue`, `developer_experience`, `architecture_pattern`, `design_pattern`, `tooling_decision`, `convention`
73
58
 
74
- [Technical explanation of:]
75
- 1. What was the ROOT CAUSE of the problem?
76
- 2. Why does the solution address this root cause?
77
- 3. What was the underlying issue (API misuse, configuration error, Rails version issue, etc.)?
59
+ ```markdown
60
+ ---
61
+ title: [Clear, descriptive title]
62
+ date: [YYYY-MM-DD]
63
+ category: [directory name under docs/solutions/, e.g. best-practices]
64
+ module: [Module or area]
65
+ problem_type: [schema enum]
66
+ component: [schema enum]
67
+ severity: [schema enum]
68
+ applies_when:
69
+ - [Condition where this applies]
70
+ tags: [keyword-one, keyword-two]
71
+ ---
78
72
 
79
- [Be detailed enough that future developers understand the "why", not just the "what"]
73
+ # [Clear, descriptive title]
80
74
 
81
- ## Prevention
75
+ ## Context
76
+ [What situation, gap, or friction prompted this guidance]
82
77
 
83
- [How to avoid this problem in future development:]
84
- - [Specific coding practice, check, or pattern to follow]
85
- - [What to watch out for]
86
- - [How to catch this early]
78
+ ## Guidance
79
+ [The practice, pattern, or recommendation with code examples when useful]
87
80
 
88
- ## Related Issues
81
+ ## Why This Matters
82
+ [Rationale and impact of following or not following this guidance]
83
+
84
+ ## When to Apply
85
+ - [Conditions or situations where this applies]
89
86
 
90
- [If any similar problems exist in docs/solutions/, link to them:]
91
- - See also: [another-related-issue.md](../category/another-related-issue.md)
92
- - Similar to: [related-problem.md](../category/related-problem.md)
87
+ ## Examples
88
+ [Concrete before/after or usage examples showing the practice in action]
93
89
 
94
- [If no related issues, write:]
95
- No related issues documented yet.
90
+ ## Related
91
+ - [Related docs or issues, if any]
92
+ ```