Explain

Explain

Explain the topic for someone seeing it for the first time, in plain terms. No filler. The output is one self-contained HTML file under ~/explain/.

Diagrams are compiled, not drawn. You describe what a diagram means; compile.py computes every pixel. Never hand-write <svg> for structure, and never write coordinates, viewBox, or path data.

Topic: $ARGUMENTS

Steps

1. Research. Ground every claim in a source you actually checked: files in the repo, docs, or pages you read. If the topic is code, read the code.

2. Draft the prose to ~/explain/<topic-slug>/doc.draft.html — plain HTML, no CSS, no JS. Where a picture beats a paragraph, put a placeholder alone on its own line:

   {{diagram: pipeline.architecture.json}}
   

   Skip the diagram when the prose already says it.

3. Write one JSON per placeholder beside the draft, named <name>.<type>.json, with semantics only. See reference.md for fields and a worked example per type. When explaining code, cite it with src: "path/to/file.py:42"; the path is checked against --root.

4. Compile with compile.py from this skill's directory (${CLAUDE_PLUGIN_ROOT}/skills/explain/compile.py when the plugin root is set):

   python3 <this skill dir>/compile.py ~/explain/<topic-slug>/doc.draft.html [--root <repo>]
   

   --root is only needed when diagrams cite src. It writes index.html beside the draft. Keep the draft and JSONs so the page can be regenerated.

5. Fix by rule code. A non-zero exit lists every problem with its fix. Edit the JSON (shorten a label, move a node's row, correct a src, split the diagram) and re-run until clean.

6. Report the output path.

Rules

• Labels are printable ASCII: ≤48 chars for nodes, ≤32 for edges, ≤91 for titles.
• One idea per diagram, six to twelve nodes. Split rather than crowd.
• Width is capped at 960px; length is free. On E_TOO_WIDE, shorten labels in the widest rank or split the diagram. Sequences scroll sideways instead; keep them to three or four participants.
• Omit rank and row unless the default layout reads badly. Then hint every node or none, and keep connected nodes on different ranks.
• Mark loops and retries with "back": true.
• No JS, no CDN, no network. The page must open offline.

Charts

The compiler handles structure, not numbers. For a bar or line chart, hand-write inline <svg> in the draft; the compiler leaves it alone. Style it yourself: a font-family, fill:currentColor, width near 900px, and ~16px text to match the prose.