Visual Explainer

One self-contained HTML page that teaches a codebase the way a senior engineer would at a whiteboard: the big picture first, then each part broken down, every claim traceable to a file and line. Every diagram is bespoke — composed for this project's real parts, boundaries and moments from the kit's primitives (a flat canvas and an isometric projection). The kit has no stock pictures; the example page shows technique, never a layout to copy.

Defaults

• Reading order: big picture → workflows → structure → state → time → call stacks. Skip a kind the subject does not have; never pad.
• Code panes off. Build with --code only when the user asks to see code; then each figure gets a source pane that follows its steps, beside the drawing on wide screens.
• One file. Publish it as an artifact when the Artifact tool is available, otherwise hand over the HTML file.

SKILL below means this skill's folder.

Steps

1. Read. Scope the subject (repo, PR, diff, feature) and read the code until you can state each fact with a file and line. For a PR, read the diff against its base, every touched file in full, and the callers of what changed. Done when you hold a fact list — every entry with path:line — plus the open questions you could not answer from the code. How to read and what to collect: references/story.md.

2. Outline. One section per reader question, in the default order, each heading phrased as the question ("What happens when a worker dies mid-run?"). Done when every section names the one thing it teaches and the figure kind that teaches it. Writing rules: references/story.md.

3. Design each diagram. Inventory the parts this figure is about using the project's own names, find the boundaries, pick the spatial metaphor that answers the section's question, and write the per-step change list. Done when each figure has a written sketch: canvas height, regions, elements with coordinates on the 960-wide grid, and what changes at every step, option or event. Method, figure kinds, isometric and motion: references/diagrams.md.