| name | distilling-lessons |
| description | Use when a bug fix, architectural change, interface contract update, or recurring pitfall has been resolved and has clear reuse value — to record a durable lesson in project memory before the context is lost |
Distilling Lessons
Overview
Every insight fades. Write it down before the context window closes.
The goal is not to have a record — it is to never repeat the same mistake. Record only when the lesson is genuinely reusable, and always anchor it to the git commit that proves the fix worked.
Core principle: A lesson that cannot be acted on by a future agent reading it cold is not worth writing.
When to Use
Use when all three of the following are true:
- The work involved a non-obvious problem, decision, or pattern
- The insight would change how you or another agent approaches a similar situation in the future
- There is a resolved git commit to anchor the lesson to
High-signal scenarios:
- Bug fixed where the root cause took investigation (not an obvious typo)
- Architectural decision made with real trade-offs considered
- Interface contract, data schema, or state management convention changed
- A pitfall you hit before, or one that is easy to repeat
Skip when:
- The change was mechanical (wording, styling, routine feature by existing pattern)
- No new knowledge was gained — you just did it
- There is no committed state to anchor the lesson to
- The insight is too project-specific to apply anywhere else
Judgment Gate
Ask yourself: "Would a fresh agent, reading this lesson cold, make a different decision?"
| Signal | Record? |
|---|
| Root cause was non-obvious | Yes |
| Solution required investigation | Yes |
| Pattern will recur in this codebase | Yes |
| Same mistake could be made again | Yes |
| Mechanical change by existing pattern | No |
| Obvious fix, no discovery involved | No |
| No committed state yet | No |
The Process
Step 1: Confirm there is a committed state
git log -1 --format='%H %s'
If nothing is committed, finish the commit first. The lesson must be anchored to real work.
Step 2: Apply the Judgment Gate
If the gate returns No, stop here. Do not record.
Step 3: Identify the target directory
Lessons go in the project's memory directory:
docs/superpowers/memory/lessons/
If the directory does not exist, create it before writing.
Step 4: Write the lesson file
Use the template in references/lesson-template.md.
File name: short, stable, hyphen-separated description of the problem — not the solution.
# Good names (problem-focused, stable)
avoid-mock-timing-in-integration-tests.md
always-migrate-schema-before-seeding.md
check-env-var-scope-before-injecting.md
# Bad names (solution-focused, vague)
fix-for-test-issue.md
bug-fix-2024.md
lesson-learned.md
Step 5: Update the index
If docs/superpowers/memory/index.md exists, add or update the lessons section with a one-line entry pointing to the new file.
If the index does not exist, do not create it just for this — note the gap instead.
Output Format
Follow the template in references/lesson-template.md.
The last_verified_commit field is mandatory. A lesson without a commit hash is unverifiable and not trustworthy.
Common Rationalizations
| Rationalization | Reality |
|---|
| "The commit message is enough" | Commit messages say what changed. Lessons say why it was non-obvious and how to avoid it next time. They serve different purposes. |
| "I'll add the commit hash later" | Later never comes. A lesson without a hash is unverifiable — it claims knowledge without evidence. Finish the commit first. |
| "I'll write a quick note and formalize next session" | NOTES.md is a graveyard. Context will be gone, the note will never be opened, and the insight will be lost exactly as if you hadn't written it. Either write the lesson properly now, or don't write it at all. |
| "It seems obvious now that I know it" | That feeling is the trap. You found it obvious after 45 minutes of investigation. A future agent starts at zero. |
| "The working code is documentation enough" | Code shows the solution. It does not show the failure mode, the non-obvious root cause, or the pattern that caused the problem. |
| "It's too project-specific to be reusable" | If the same mistake can recur in this project, the lesson belongs in this project's memory. |
Red Flags
Over-recording:
- Writing a lesson after every commit "just in case"
- Recording lessons with vague rules like "be careful with async code"
- Lessons that duplicate what is already in CLAUDE.md or AGENTS.md
Under-recording:
- Closing a complex bug and moving on immediately
- Thinking "I'll remember this" after a painful investigation
- Skipping because "it seems obvious now that I know it"
- Writing a "quick note" in NOTES.md instead of a real lesson doc
Bad lessons:
- No
last_verified_commit field
- Rule so general it applies to everything ("test your code")
- Situation description too vague to recognize on re-encounter
- "When NOT to Apply" section missing, leaving the rule over-broad
Integration
Called after:
systematic-debugging — when a root cause was found and fixedfinishing-a-development-branch — during the memory gate stepcurating-repository-memory — as a complement for lesson-type docs
Pairs with:
curating-repository-memory for broader memory updates (module cards, decisions, contracts)bootstrapping-repository-memory when lessons directory does not yet exist
Does NOT replace:
curating-repository-memory for module cards, contracts, or decisions- CLAUDE.md / AGENTS.md for project-level conventions that apply to all future work
