| name | learn |
| description | Use when the user types /learn or says "extract the lesson", "capture the lesson", or "what did we learn" after finishing a study, bug fix, or feature — to distill a piece of work into one reusable lesson file at learn/<slug>.md in the current repo. The work can come from an explicit topic, a file or diff pointed at, recent git activity, or the conversation. Output is a single concept future-you can reread cold. |
Learn
Turn a piece of work into ONE reusable lesson. Not a changelog, not a recap of every
step — the single insight worth keeping. Works in any repo.
When to use
- User typed
/learn or asked to "extract the lesson".
- A study, fix, or feature wrapped and there's a finding worth one file.
When NOT to use
- Before there's a conclusion. No conclusion → nothing to learn.
- To document code structure or how-to steps (that belongs in the repo's docs / comments).
Find the subject (chat- and repo-agnostic)
Don't assume the lesson lives in the current conversation. Take the subject from the first
of these that's present:
- An explicit topic or
/learn <topic> the user gives.
- A file, path, or diff the user points at (read it).
- Recent work in the current repo —
git log -5, git diff, latest commit message.
- The current conversation, if it carries a real finding.
If none yield a clear, concluded finding, ask the user what the lesson is — don't invent one.
Procedure
- Determine the subject (above).
- Pick the single most reusable insight. If there are several, choose the one with the
broadest future payoff and write only that. One lesson per file.
- Choose a short kebab-case slug naming the concept (e.g.
cache-needs-explicit-ttl).
- Write
learn/<slug>.md at the repo root with exactly the structure below. Create the
learn/ directory if it doesn't exist.
- Tell the user the path and the one-line takeaway.
File structure (required)
# <Concept in plain English>
## The Question
What was being figured out — one or two sentences.
## What I Found
The result, 2–3 sentences. If a number matters, state it.
## Why It Works (or doesn't)
The underlying mechanism in plain language. No jargon you wouldn't say out loud.
## The Takeaway
The one thing future-you should remember.
Rules
- No code dumps. Reference a file path if needed; don't paste the code.
- No jargon you wouldn't say out loud. Plain English wins.
- If a number carries the lesson, state the number.
- One lesson per file. Resist appending a second.
Common mistakes
- Writing a recap of what was done instead of what was learned. Test: would this help
someone who never saw the work? If it reads like a diary entry, rewrite as a lesson.
- Burying the takeaway. It's a named section — make it stand alone.
