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

• • Exact error messages (copy-paste, not paraphrased)
• • Specific file:line references
• • Failed attempts documented (helps avoid wrong paths)
• • Technical explanation (not just "what" but "why")
• • Prevention guidance