Take a code change, recover the prompt that produced it, and write a lesson the creator reads straight into the camera.
The lesson teaches the decisions, not the code. A viewer can get a file by file walkthrough from their own agent in ten seconds. Recorded minutes spent on one waste the only thing a human has and the agent does not.
Three things transfer to a different codebase. Why the change is shaped this way, what the alternative would have cost, and which rule got written down so the decision survives.
Here is the test. A creator opens the file after two weeks away from the code. They record, and they work through it without a pause to think.
Steps
Copy this checklist into your response and tick items off as you go. The verify step is the one that gets skipped, and skipping it puts unchecked claims in front of an audience.
- [ ] 1. Scope the change
- [ ] 2. Recover the prompt
- [ ] 3. Study the change
- [ ] 4. Verify, and show the user what failed
- [ ] 5. Write the lesson
- [ ] 6. Hand it back
1. Find the change
Follow references/shared/change-analysis.md, the scoping section. Gather the git state first, then ask which slice to teach using real numbers.
Pay attention to the untracked files warning there. It is the most common cause of a broken lesson.
2. Recover the prompt
The prompt is the thing viewers came for. Do not ask for it until you have looked.
Follow references/shared/prompt-recovery.md. It detects which agent wrote the code, then searches that agent's history by content rather than by path, because storage paths drift between versions.
If you find it, quote it exactly. Do not clean it up. A real prompt with a typo teaches more than a polished one. The follow-up correction is a step of its own, because it shows the decision as it was made.
Never invent a prompt. If it cannot be recovered and the user cannot remember it, say so in the lesson and teach the change on its own terms.
3. Find the architecture
Read references/lesson.md now, not later. It covers what counts as lesson material, what to look for, and how the lesson is ordered. Read the diff without it and you produce notes you have to redo.
Use references/shared/change-analysis.md for the mechanics of reading the diff. Read the changed files in full, but read them looking for judgment calls rather than for a walkthrough order.
Pay attention to anything that looks like it could be simpler. Odd code is usually a gotcha with the explanation removed. Recover that explanation and you have the best thirty seconds in the lesson.
Where you cannot work out why a line exists, ask the user. Do not invent a reason.
If the change turns out to have no decisions in it, say so instead of inflating a small change into a long lesson.
4. Verify
Run the verify gate in references/shared/change-analysis.md and show the user anything that fails before writing a word.
5. Write the lesson
Follow the order, weight, register, and format in references/lesson.md. Use references/spoken-voice.md for the language rules. The first controls what gets taught and in what order. The second controls whether the words can be read out loud, and that is where most generated scripts fail.
Include the delegation prompt, written specific to this change, so the viewer can get the code walkthrough from their own agent.
Write to docs/lessons/ in the repo, named NN-slug.md, continuing whatever numbering exists. If the directory does not exist, create it and start at 01. If the repo already has a lessons folder under a different name, use that.
6. Hand it back
Report the file path, the estimated runtime, and the flaws found in the feature. Do not summarize the lesson back to the user. They are about to read it.
Offer one thing. To rewrite any step that does not sound like them. Voice needs a human pass, and a first draft rarely survives being read out loud.
What makes this different from documentation
Documentation explains what the code does. This explains how a person got an AI to write it, which is a different subject with a different shape.
A viewer should come away able to do four things. Make the same decision on a different codebase. Write a prompt like that one. Know what to check in a plan before they approve it. Recognise the gotchas before they hit them.
To recognise this specific code is not on the list.
The decision and the gotchas carry the lesson. A quarter of the runtime goes to the decision alone.
Reference files
Skill-specific.
references/lesson.md: what to teach, what to look for, the order, the weight, the register, and the formatreferences/spoken-voice.md: how to write words that can be read out loud
Shared across the repo, synced into references/shared/ from /shared.
references/shared/simplified-english.md: ASD-STE100, the sentence and vocabulary rulesreferences/shared/voice.md: house style, all mediumsreferences/shared/change-analysis.md: scoping a diff, reading it, verifying claimsreferences/shared/prompt-recovery.md: finding the prompt in any agent's historyreferences/shared/tool-comparison.md: when a comparison is real and when it is filler