distilling-lessons

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:

1. The work involved a non-obvious problem, decision, or pattern
2. The insight would change how you or another agent approaches a similar situation in the future
3. 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 fixed
• finishing-a-development-branch — during the memory gate step
• curating-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