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
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.
Use when all three of the following are true:
High-signal scenarios:
Skip when:
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 |
git log -1 --format='%H %s'
If nothing is committed, finish the commit first. The lesson must be anchored to real work.
If the gate returns No, stop here. Do not record.
Lessons go in the project's memory directory:
docs/superpowers/memory/lessons/
If the directory does not exist, create it before writing.
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
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.
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.
| 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. |
Over-recording:
Under-recording:
Bad lessons:
last_verified_commit fieldCalled 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 docsPairs with:
curating-repository-memory for broader memory updates (module cards, decisions, contracts)bootstrapping-repository-memory when lessons directory does not yet existDoes NOT replace:
curating-repository-memory for module cards, contracts, or decisions