learn

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:

1. An explicit topic or /learn <topic> the user gives.
2. A file, path, or diff the user points at (read it).
3. Recent work in the current repo — git log -5, git diff, latest commit message.
4. 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

1. Determine the subject (above).
2. 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.
3. Choose a short kebab-case slug naming the concept (e.g. cache-needs-explicit-ttl).
4. Write learn/<slug>.md at the repo root with exactly the structure below. Create the learn/ directory if it doesn't exist.
5. 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.