| name | documenting-solutions |
| description | Use when a non-trivial problem has been solved and verified working -- captures the solution as searchable institutional knowledge |
Documenting Solutions
Overview
Capture solved problems as searchable documentation. Non-trivial problems only — skip typos and obvious fixes.
When to Document
Document when:
- Multiple investigation attempts were needed
- Debugging took significant time
- Solution was non-obvious
- Future sessions would benefit from knowing this
Skip when:
- Simple typos or syntax errors
- Trivial fixes immediately corrected
- Standard practices well-documented elsewhere
Steps
1. Gather Context
Extract from the session:
- Symptom — Observable error/behavior (exact error messages)
- Investigation — What didn't work and why
- Root cause — Technical explanation
- Solution — What fixed it (code/config changes)
- Prevention — How to avoid in future
2. Check for Similar Issues
rg "error message keywords" docs/solutions/
If similar issue found: cross-reference. If same root cause: update existing doc.
3. Create Documentation
Save to: docs/solutions/YYYY-MM-DD-symptom-description.md
# [Symptom Description]
**Date:** YYYY-MM-DD
**Component:** [what was affected]
**Severity:** critical|high|medium|low
## Symptom
[Exact error message or observable behavior]
## Investigation
[What was tried and why it didn't work]
## Root Cause
[Technical explanation of the actual problem]
## Solution
[What fixed it — include code if helpful]
## Prevention
[How to avoid this in the future]
## Related
[Links to similar issues if any]
4. Cross-Reference (if applicable)
If 3+ similar issues exist, consider creating a pattern entry:
## [Pattern Name]
**Common symptom:** [description]
**Root cause:** [technical explanation]
**Solution pattern:** [general approach]
Quality Checklist
