| name | bug-learning |
| description | Use after fixing or investigating a hard-earned bug that took significant debugging, crossed multiple files or systems, had misleading symptoms, or revealed durable system behavior worth preserving in docs/knowledge/learnings. |
Bug Learning
Capture only hard-earned bug knowledge, not ordinary bug reports.
Workflow
- Confirm the bug qualifies: long investigation, many steps, misleading symptoms, cross-system behavior, or a durable invariant.
- Inspect the final fix, regression tests, logs, affected feature packs, and key files.
- Read git history for the affected files and feature terms; keep only major relevant history.
- Create the learning with
knowledge learning "<Title>".
- Use
references/bug-learning.md for the file shape.
- Write the root cause as a mechanism, not a symptom.
- Record why detection was hard and the durable rule future agents should remember.
- Document regression protection: tests, guards, monitoring, or code paths.
- Link the learning from related feature packs under
Known Learnings.
- Update glossary terms, aliases, index entries, and
key_files when the investigation reveals durable knowledge.
- Run
knowledge check.
Rules
- Do not create learnings for obvious one-file fixes, typos, routine edge cases, or temporary incidents.
- Do not preserve debugging noise, every failed hypothesis, or minor commits.
- Do not call the learning complete without regression protection or a clear reason none applies.