@fro.bot/systematic 3.26.1 → 3.26.3
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.
- package/ATTRIBUTIONS.md +2 -2
- package/HARNESSES.md +23 -8
- package/agents/research/learnings-researcher.md +82 -80
- package/dist/index.js +20 -2
- package/dist/lib/bootstrap.d.ts +17 -2
- package/dist/lib/pi-subagents-personas.d.ts +1 -1
- package/dist/pi.js +23 -5
- package/package.json +5 -5
- package/skills/ce-compound/SKILL.md +13 -11
- package/skills/ce-compound/references/schema.yaml +99 -15
- package/skills/ce-compound/references/yaml-schema.md +36 -7
- package/skills/ce-compound-refresh/SKILL.md +33 -16
- package/skills/ce-compound-refresh/references/schema.yaml +99 -15
- package/skills/ce-compound-refresh/references/yaml-schema.md +36 -7
- package/skills/ce-review/SKILL.md +5 -5
- package/skills/ce-review/references/review-output-template.md +1 -1
- package/skills/compound-docs/SKILL.md +75 -124
- package/skills/compound-docs/assets/resolution-template.md +65 -68
- package/skills/compound-docs/references/schema.yaml +331 -0
- package/skills/compound-docs/references/yaml-schema.md +122 -54
- package/skills/git-clean-gone-branches/SKILL.md +17 -7
- package/skills/git-worktree/SKILL.md +33 -309
- package/skills/git-worktree/scripts/worktree-manager.sh +568 -391
- package/skills/orchestrating-subagents/SKILL.md +1 -1
- package/skills/using-systematic/references/worktree-placement.md +1 -0
- package/skills/compound-docs/assets/critical-pattern-template.md +0 -34
- package/skills/compound-docs/schema.yaml +0 -176
|
@@ -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
|
|
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
|
-
**
|
|
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
|
-
|
|
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
|
-
**
|
|
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
|
-
**
|
|
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
|
-
-
|
|
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
|
|
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
|
|
84
|
-
2.
|
|
85
|
-
|
|
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-symptom-or-title]-[module]-[YYYYMMDD].md`
|
|
142
|
+
|
|
143
|
+
Bug-track docs name the file after the symptom. Knowledge-track docs have no symptom, so they use 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
|
-
- `
|
|
141
|
-
- `parameter-not-saving-state-
|
|
142
|
-
- `webview-crash-on-resize-Assistant-20251110.md`
|
|
154
|
+
- `n-plus-one-report-generation-ReportService-20251110.md` (bug track)
|
|
155
|
+
- `parameter-not-saving-state-Checkout-20251110.md` (bug track)
|
|
156
|
+
- `webview-crash-on-resize-Assistant-20251110.md` (bug track)
|
|
157
|
+
- `prefer-explicit-request-timeouts-HttpClient-20251110.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
|
|
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
|
|
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
|
|
205
|
+
# Create directory on first use
|
|
187
206
|
mkdir -p "docs/solutions/${CATEGORY}"
|
|
188
207
|
|
|
189
|
-
# Write documentation using template
|
|
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
|
|
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
|
|
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.
|
|
274
|
-
3.
|
|
275
|
-
4.
|
|
276
|
-
5.
|
|
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:
|
|
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
|
|
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.,
|
|
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
|
|
283
|
+
**Option 4: View documentation**
|
|
334
284
|
|
|
335
285
|
- Display the created documentation
|
|
336
286
|
- Present decision menu again
|
|
337
287
|
|
|
338
|
-
**Option
|
|
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:
|
|
465
|
-
- Symptom:
|
|
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:
|
|
468
|
-
- Root cause: Missing eager loading causing separate database query per
|
|
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-
|
|
421
|
+
4. **Generate filename:** `n-plus-one-report-generation-ReportService-20251110.md`
|
|
471
422
|
5. **Validate YAML:**
|
|
472
423
|
```yaml
|
|
473
|
-
module:
|
|
424
|
+
module: Report Service
|
|
474
425
|
date: 2025-11-10
|
|
475
426
|
problem_type: performance_issue
|
|
476
|
-
component:
|
|
427
|
+
component: backend
|
|
477
428
|
symptoms:
|
|
478
|
-
- "N+1 query when loading
|
|
479
|
-
- "
|
|
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-
|
|
437
|
+
- `docs/solutions/performance-issues/n-plus-one-report-generation-ReportService-20251110.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-
|
|
446
|
+
- docs/solutions/performance-issues/n-plus-one-report-generation-ReportService-20251110.md
|
|
496
447
|
|
|
497
448
|
What's next?
|
|
498
449
|
1. Continue workflow (recommended)
|
|
499
|
-
2.
|
|
500
|
-
3.
|
|
501
|
-
4.
|
|
502
|
-
5.
|
|
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
|
-
|
|
15
|
+
title: [Clear problem title]
|
|
3
16
|
date: [YYYY-MM-DD]
|
|
4
|
-
|
|
5
|
-
|
|
17
|
+
category: [docs/solutions subdirectory]
|
|
18
|
+
module: [Module or area]
|
|
19
|
+
problem_type: [schema enum]
|
|
20
|
+
component: [schema enum]
|
|
6
21
|
symptoms:
|
|
7
|
-
- [Observable symptom 1
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
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
|
-
#
|
|
29
|
+
# [Clear problem title]
|
|
17
30
|
|
|
18
31
|
## Problem
|
|
19
|
-
[1-2 sentence
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
52
|
-
|
|
53
|
-
# Before (broken):
|
|
54
|
-
[Show the problematic code]
|
|
46
|
+
## Prevention
|
|
47
|
+
- [Concrete practice, test, or guardrail]
|
|
55
48
|
|
|
56
|
-
|
|
57
|
-
[
|
|
49
|
+
## Related Issues
|
|
50
|
+
- [Related docs or issues, if any]
|
|
58
51
|
```
|
|
59
52
|
|
|
60
|
-
|
|
61
|
-
```ruby
|
|
62
|
-
# Migration change:
|
|
63
|
-
[Show what was changed in the migration]
|
|
64
|
-
```
|
|
53
|
+
---
|
|
65
54
|
|
|
66
|
-
|
|
67
|
-
```bash
|
|
68
|
-
# Steps taken to fix:
|
|
69
|
-
[Commands or actions]
|
|
70
|
-
```
|
|
55
|
+
## Knowledge Track Template
|
|
71
56
|
|
|
72
|
-
|
|
57
|
+
Use for: `best_practice`, `documentation_gap`, `workflow_issue`, `developer_experience`, `architecture_pattern`, `design_pattern`, `tooling_decision`, `convention`
|
|
73
58
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
59
|
+
```markdown
|
|
60
|
+
---
|
|
61
|
+
title: [Clear, descriptive title]
|
|
62
|
+
date: [YYYY-MM-DD]
|
|
63
|
+
category: [docs/solutions subdirectory]
|
|
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
|
-
[
|
|
73
|
+
# [Clear, descriptive title]
|
|
80
74
|
|
|
81
|
-
##
|
|
75
|
+
## Context
|
|
76
|
+
[What situation, gap, or friction prompted this guidance]
|
|
82
77
|
|
|
83
|
-
|
|
84
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
91
|
-
|
|
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
|
-
|
|
95
|
-
|
|
90
|
+
## Related
|
|
91
|
+
- [Related docs or issues, if any]
|
|
92
|
+
```
|