explain-it

Turn code you have investigated into a small static HTML site that a smart reader with zero context on this codebase can follow: a root page that builds the mental model, one page per topic, and a sidebar connecting them.

The bar to hit: "simple language that is not too simple and not too difficult." Never talk down; never assume repo knowledge.

Workflow

1. Investigate before you explain

Never explain code you have not read. For every topic, read the actual source: the changed lines, the enclosing function, and at least one caller, so you can answer "when does this code even run?" with a true story. If a claim came from someone else (a review comment, an issue), verify it against the code first and say so if it doesn't hold.

2. Plan the site

• One root page (index.html): the primer. It builds the reader's mental model of the system in ~2 minutes and links to every topic page.
• One page per topic (01-<slug>.html, 02-<slug>.html, …): each page explains one change, bug, decision, or subsystem. 3–7 pages is the sweet spot; merge topics rather than exceed ~9.
• A shared sidebar on every page listing all pages in reading order, with the current page highlighted. Pages are plain files linked with relative <a href> — the site must work opened directly from disk (file://), so no routers, no build step, no external JS.

Ask the user where to put the folder only if no location is obvious; otherwise create a sensibly named folder next to the work (e.g. docs/explainers/<topic>/) and say where you put it.

3. Write each page

Follow references/writing-guide.md for the method — read it before writing your first page. The non-negotiables:

• Primer first. The root page introduces every domain concept the topic pages need, each with one concrete metaphor (e.g. "a release is a photocopy; a running job pins one photocopy"). Introduce a metaphor once, then reuse it verbatim everywhere. Never stack two metaphors for one concept.
• Ground every topic in runtime. Each topic page opens with a "When does this code even run?" story: 2–4 actor beats (User does X → System runs function Y → the tiny job inside it). Real function names in code font, alongside — never instead of — the plain-language story.
• Show the change as a diff. Old vs new code in red/green diff blocks with the file path in the header, trimmed to the crux, with 1–3 inline comments pointing at why — not narrating what.
• Quantify the "why". "Slow" is banned; "hundreds of KB per request, ~99% of the time for nothing" is the standard. Same for risk: name the concrete input/state and the wrong outcome.
• Separate bugs from decisions. If something is a defensible product choice rather than a defect, present it as a decision with the trade-off, not as a mistake.
• End the root page with a scoreboard: a status table of every item (done / proposed / parked) with its location in the codebase.

4. Build the HTML

Copy references/site-template.html as the starting point for every page — it contains the design tokens, the sidebar, and one working example of every component (story block, callout, diff block, status table, pills). Then:

• Keep each page fully self-contained (all CSS inline in the page). The sidebar is duplicated into each page with the current item marked class="on".
• Follow references/design-system.md for tokens and component rules. Keep the palette, spacing, and type scale as given so multi-page sites look like one system. The template ships a light/dark toggle and a collapsible sidebar — carry both into every page rather than dropping them.
• No external dependencies except the Google Fonts link already in the template (the font stack falls back cleanly offline) and no JS beyond the template's theme-toggle snippet.

5. Verify before handing over

Open or render the root page and at least one topic page (or re-read them) and check: every sidebar link resolves, every code identifier mentioned in prose exists in the codebase with that exact spelling, every diff compiles conceptually against the real file, and the scoreboard statuses are current. Then tell the user the folder path and open the root page for them if the environment allows.

Common pitfalls

• Explaining from memory of the conversation instead of the code — the explainer inherits every stale claim. Re-read the source.
• Metaphor drift: calling it "photocopy" on one page and "frozen copy" on the next. One term, everywhere.
• Diff blocks that paste 60 lines verbatim. Trim to the crux; keep 2–4 context lines around it.
• Prose that narrates the diff line by line. The diff shows what; prose only carries why it matters and when it runs.
• A sidebar that only exists on the index page. Every page carries the full sidebar.
• Baby-talk ("the computer remembers things in a special box"). The reader is smart — they just don't know this codebase.