| name | compound-docs |
| description | Use when a hard problem was just solved and the solution should be captured as a learning for future reference |
| tags | ["knowledge","documentation","learning"] |
| triggers | ["that worked","figured it out","the issue was","hard problem solved","lesson learned","tricky bug fixed"] |
| chains_to | ["propose-skill-update"] |
| priority | core |
| gate | false |
Compound Docs (Lessons Learned)
Quick Reference
After solving a hard problem, propose capturing the solution as a learning. The user approves before anything is written. Learnings compound — the next time this problem appears, the solution is already documented.
When to Use
- A non-obvious bug was debugged and fixed
- A workaround was needed for a library/framework limitation
- An integration required trial and error to get right
- A configuration or setup issue took significant effort
- The user says something like "that was tricky" or "finally figured it out"
When NOT to Use
- Routine work with no novel insights
- The solution is obvious from the docs
- The user explicitly declines to capture it
Core Process
Step 1: Detect the Trigger
After solving a hard problem, propose the learning:
"That was a non-trivial fix. Want me to capture this as a lesson learned? It'll help if this comes up again."
If the user says no, move on. No insistence.
Step 2: Write the Learning
Create a file at docs/learnings/<category>/<filename>.md:
---
date: YYYY-MM-DD
category: <category>
tags: [tag1, tag2]
---
# <Title: What the Problem Was>
## Problem
[1-3 sentences: what went wrong and how it manifested]
## Root Cause
[1-3 sentences: why it happened]
## Solution
[The fix, with code if relevant]
## Key Insight
[One sentence: the non-obvious thing that made this hard]
## References
- [Link or file:line if relevant]
Categories
Use these categories (create new ones only if none fit):
| Category | When |
|---|
debugging | Bug fixes, error resolution |
configuration | Setup, environment, tooling issues |
integration | API, library, service integration |
performance | Optimization insights |
architecture | Structural decisions and their outcomes |
testing | Test strategy, mocking, fixtures |
deployment | Build, deploy, CI/CD issues |
Step 3: Present for Approval
Show the proposed learning to the user. They approve before it's written to disk.
Keep the proposal concise — the learning file has the details.
Step 4: Consider Skill Updates
If you've captured 3+ learnings about the same topic, chain to propose-skill-update — there might be a pattern worth codifying.
Anti-Patterns
| Anti-Pattern | Why It's Wrong |
|---|
| Capturing everything | Not every fix is worth documenting. Only non-obvious ones. |
| Writing without user approval | The user decides what's worth keeping. |
| Long, essay-style learnings | Keep it scannable. Problem → Root Cause → Solution → Insight. |
| Duplicating existing learnings | Check docs/learnings/ first. Update if it already exists. |
| Capturing the "what" without the "why" | The root cause and key insight are the valuable parts. |
Chaining
OPTIONAL: syntaxninja-dojo:propose-skill-update (when 3+ learnings suggest a pattern)
