Capture a Lesson from a Bug Fix
Goal
Document a debugging breakthrough immediately after solving it, so the solution is searchable in future sessions instead of being lost in a chat thread.
Prerequisites
- KMGraph initialized (
/kmgraph:init) - A solved bug with the root cause identified
Steps
1. Run the capture command immediately after solving
/kmgraph:capture-lesson
The command prompts for a title, description, and category. Choose debugging for bug investigations.
2. Fill in the lesson fields
| Field | What to write |
|---|---|
| Title | Short phrase naming the root cause: "Redis connection timeout on cold start" |
| Problem | What the bug looked like from the outside |
| Root cause | The actual cause — be specific |
| Solution | Exactly what fixed it |
| Prevention | How to avoid it next time |
| Tags | Technology names, error codes, affected modules |
3. Let git metadata attach automatically
If git is enabled, the lesson captures the current branch, commit hash, and any linked issue number. No action needed.
4. Use --snapshot when context is rich
If the debugging session involved many steps, add a session snapshot first:
/kmgraph:capture-lesson --snapshot
This preserves the full session context alongside the lesson.
Verify
/kmgraph:recall "the bug title or keywords"
The lesson should appear in results. If not, run /kmgraph:update-graph to extract patterns.
Next steps
- Capture the pipeline diagram explained
- Write a pattern entry if the bug reveals a reusable pattern
- Create an ADR if the fix changes architecture