/explain-code

The reader does not need the code read to them. They need to be able to predict what it does. Get them there with one real run, followed through the real files.

Load explain as well for the teaching doctrine and the brief template; this skill is the code-specific part.

1. Decide the size of the answer

The ask	Answer
"What is this file / function for?"	Chat: purpose, then 2–4 behaviours. No board.
"How does X work?" with one path through 1–3 files	Chat trace, or a short board if the path crosses modules.
"Walk me through…", a flow across modules, architecture, lifecycles, data shape	The board sub-agent, with a trace brief.
A concept the code uses (debounce, event loop, CRDT, auth flow)	Concept first, then where it lives in this code.

2. Gather facts before you teach

Read the code. Never explain from memory what you can open.

• Find the entry point (route handler, exported function, event listener, command). Use grep/glob/code search, then read the real file.
• Pick one concrete run: a specific call with specific values. Take the values from a test, a fixture, a log line or the types. "POST /sessions {user: 'ana'}", not "the request".
• Follow the values file by file, in execution order. Note for each step: file path and line, the function name, what the values look like after it.
• Find the surprise: the branch, the cache, the retry, the lock — the thing that makes the code more than a straight line. That is what the reader will need the second case for.
• Find the second run: the same entry with one input changed (empty, error, repeated, large). Note where the paths split.
• If the code uses a named idea (queue, saga, memoisation), write the one-sentence plain definition you will give after the trace, not before it.

Stop reading when you can say the trace aloud with real names and values. Do not map the whole repo.

3. Shape the explanation

Use the ladder: ground → trace → vary → climb → descend.

1. Ground. One sentence on what the user wants out of it ("When someone clicks Save, what actually writes to disk?"), then the concrete run.
2. Trace. 4–7 steps. Each step: the real function name, what it does to the values, and why the next step needs it. A marker (the request, the job, the value) travels along the flow.
3. Vary. The second run next to the first. Only the difference is highlighted.
4. Climb. The rule in one or two sentences, in plain words, then the proper name of the idea if there is one.
5. Descend. One thing that looked odd, now explained by the rule.

Plain words first, then the code's own names. Describe a function by its job ("checks the user is allowed") and give the identifier beside it. Skip imports, boilerplate, logging and getters unless they are the point.

4. Brief for the board

Send the storyboard from explain, with these code specifics:

• Name each stage with the real identifier and file, e.g. createSession() api/sessions.ts. Give ref paths with a line range so shapes link to code.
• Give the exact marker text at each stage (req {user: 'ana'} → row inserted id=7 → 201 {id: 7}), so the sub-agent never invents values.
• Say which stages stay fixed and which one changes between the two runs.
• Ask for a real three-line snippet only where the code is the surprise. Give the snippet verbatim in the brief.
• Use the right metaphor of space: flow left to right in execution order; the places things are stored (database, cache, disk) as a different shape, below the flow.
• Icons are fine for the kinds of thing (database, server, globe, user, lock, file-text) — name them in the brief; the sub-agent places them with board_image source icon. Never an icon in place of a label.

5. Chat reply

Two or three lines: what the code does in plain words, the one surprise, and what is on the board. No restating the code.

Checks

• Every name, path and value in the answer came from a file you read.
• A reader who has not seen the repo could repeat the trace.
• The concept is named only after it has been seen working.
• One idea per board. If it needs two, make two boards.