Visual Report
Turn a subject (a system, a process, research findings, a decision) into a single self-contained HTML document that carries its meaning in visuals, not paragraphs. Tailwind and Mermaid come from CDNs; hand-built CSS/SVG handles the editorial visuals Mermaid can't.
VISUAL-LANGUAGE.md names the diagram patterns and is the single source for which pattern to pick for a given idea. The full scaffold, diagram build recipes, interactivity rules, and house style live in HTML-REPORT.md.
Process
Report on the subject you were given, at the scope asked. If exploring surfaces a bug, a stale doc, or a design problem, note it in the report; don't go fix it.
1. Explore
Find the subject and where its substance lives, then gather from there:
- About the codebase? Use the Agent tool with
subagent_type=Explore to walk it: one dispatch for the whole walk, not one per module, and none for the writing. Don't dump files into the report; extract the structure worth drawing.
- Already in the conversation? The analysis is done (a finished design discussion, a debugging session, a research summary). Organize what's there; don't re-investigate.
- Pointed at sources? Read the named docs/URLs.
If you're in a repo, read docs/adr/. ADRs record decisions the report should reflect, and it should not contradict them silently. Stop exploring once you can draw the thing; over-exploring a subject that's already settled wastes the run.
2. Visualize
Write one self-contained HTML file and open it.
- Where: default to the OS temp dir. Resolve
$TMPDIR, fall back to /tmp (or %TEMP% on Windows), at <tmpdir>/<slug>-<timestamp>.html. If the user names a destination ("save to docs/") or says "keep/commit it," write there instead. Either way, print the absolute path and open it (open on macOS, xdg-open on Linux, start on Windows). If opening fails (headless/SSH session), just print the path and say so.
- Self-contained: one file, no build step, portable. The only dependencies are the Tailwind CDN and the Mermaid ESM import, so it renders fully only with network access. Light interactivity (collapsible sections, before/after toggles, CSS animations) is allowed via inline vanilla JS only, no extra libraries. "Self-contained" throughout this skill means exactly this.
- Visual-first: every major idea earns a visual, and the report runs as long as the subject has ideas. A five-idea subject gets five visuals, not twelve sections propped up by an intro, a recap, and a conclusion. To pick the pattern that fits each idea, consult the "Picking between them" decision tree in VISUAL-LANGUAGE.md; don't default to a Mermaid flowchart for everything. Once you've chosen a pattern, get its build recipe in HTML-REPORT.md. If a section needs a paragraph to be understood, redraw the visual.
- House style: the editorial aesthetic in HTML-REPORT.md is the style, lean, not corporate-dashboard. Apply it; don't invent a new look per report.
- Verify: a Mermaid syntax error never fails loudly; it renders as an error blob in the page. Before handing over, re-read every Mermaid block for the known footguns (quote labels containing parentheses, colons, or HTML), then check the rendered page for no error blobs and every diagram legible. Fix and reload until it's clean.
Cite ADRs (if applicable). When the report depicts something governed by an existing ADR, cite it in an amber callout ("this flow follows ADR-0012") so a reader can trace why it's built this way to the decision record. Only when an ADR genuinely governs what's drawn; never staple an ADR callout onto every diagram.
3. Grill loop
After the file is written, hand it over in one sentence: what the report covers and where it is. Then interview the user relentlessly about what the report gets wrong or underweights, whether that's a section, a diagram pattern choice, or the emphasis, until it says what they mean. Ask the questions one at a time, as plain prose, and give your recommended answer with each. If a question can be answered by re-reading the sources or codebase, do that instead of asking. Iterate on the same file after each answer; stop when the user has nothing left to change.
Propose an ADR (if applicable). If the grilling surfaces a load-bearing decision nobody had recorded, where the visualization made a design choice explicit and a future reader would wonder "why this way?", offer to draft one: "Want me to record this as an ADR?" Only when it clears three tests: it's hard to reverse, it's surprising without context, and it's the result of a real trade-off. Skip ephemeral or self-evident reasons.
1---2name: visual-report3description: Produce a single self-contained HTML visual report, an explainer, writeup, or diagram-heavy document built with Tailwind and Mermaid via CDN plus hand-crafted CSS/SVG. Use when the user wants a visual report, an explainer, a single-file HTML writeup of a system/process/findings, or asks to visualize or diagram something as a shareable document.4---56# Visual Report78Turn a subject (a system, a process, research findings, a decision) into a single self-contained HTML document that **carries its meaning in visuals**, not paragraphs. Tailwind and Mermaid come from CDNs; hand-built CSS/SVG handles the editorial visuals Mermaid can't.910[VISUAL-LANGUAGE.md](references/VISUAL-LANGUAGE.md) names the diagram patterns and is the single source for **which** pattern to pick for a given idea. The full scaffold, diagram **build recipes**, interactivity rules, and house style live in [HTML-REPORT.md](references/HTML-REPORT.md).1112## Process1314Report on the subject you were given, at the scope asked. If exploring surfaces a bug, a stale doc, or a design problem, note it in the report; don't go fix it.1516### 1. Explore1718Find the subject and where its substance lives, then gather from there:1920- **About the codebase?** Use the Agent tool with `subagent_type=Explore` to walk it: one dispatch for the whole walk, not one per module, and none for the writing. Don't dump files into the report; extract the structure worth drawing.21- **Already in the conversation?** The analysis is done (a finished design discussion, a debugging session, a research summary). Organize what's there; don't re-investigate.22- **Pointed at sources?** Read the named docs/URLs.2324If you're in a repo, read `docs/adr/`. ADRs record decisions the report should reflect, and it should not contradict them silently. Stop exploring once you can draw the thing; over-exploring a subject that's already settled wastes the run.2526### 2. Visualize2728Write one self-contained HTML file and open it.2930- **Where:** default to the OS temp dir. Resolve `$TMPDIR`, fall back to `/tmp` (or `%TEMP%` on Windows), at `<tmpdir>/<slug>-<timestamp>.html`. If the user names a destination ("save to `docs/`") or says "keep/commit it," write there instead. Either way, **print the absolute path and open it** (`open` on macOS, `xdg-open` on Linux, `start` on Windows). If opening fails (headless/SSH session), just print the path and say so.31- **Self-contained:** one file, no build step, portable. The only dependencies are the Tailwind CDN and the Mermaid ESM import, so it renders fully only with network access. Light interactivity (collapsible sections, before/after toggles, CSS animations) is allowed via **inline vanilla JS only**, no extra libraries. "Self-contained" throughout this skill means exactly this.32- **Visual-first:** every major idea earns a visual, and the report runs as long as the subject has ideas. A five-idea subject gets five visuals, not twelve sections propped up by an intro, a recap, and a conclusion. To pick the pattern that fits each idea, consult the "Picking between them" decision tree in [VISUAL-LANGUAGE.md](references/VISUAL-LANGUAGE.md); don't default to a Mermaid flowchart for everything. Once you've chosen a pattern, get its build recipe in [HTML-REPORT.md](references/HTML-REPORT.md). If a section needs a paragraph to be understood, redraw the visual.33- **House style:** the editorial aesthetic in [HTML-REPORT.md](references/HTML-REPORT.md) is the style, lean, not corporate-dashboard. Apply it; don't invent a new look per report.34- **Verify:** a Mermaid syntax error never fails loudly; it renders as an error blob in the page. Before handing over, re-read every Mermaid block for the known footguns (quote labels containing parentheses, colons, or HTML), then check the rendered page for no error blobs and every diagram legible. Fix and reload until it's clean.3536**Cite ADRs (if applicable).** When the report depicts something governed by an existing ADR, cite it in an amber callout (_"this flow follows ADR-0012"_) so a reader can trace *why it's built this way* to the decision record. Only when an ADR genuinely governs what's drawn; never staple an ADR callout onto every diagram.3738### 3. Grill loop3940After the file is written, hand it over in one sentence: what the report covers and where it is. Then interview the user relentlessly about what the report gets wrong or underweights, whether that's a section, a diagram pattern choice, or the emphasis, until it says what they mean. Ask the questions one at a time, as plain prose, and give your recommended answer with each. If a question can be answered by re-reading the sources or codebase, do that instead of asking. Iterate on the same file after each answer; stop when the user has nothing left to change.4142**Propose an ADR (if applicable).** If the grilling surfaces a load-bearing decision nobody had recorded, where the visualization made a design choice explicit and a future reader would wonder "why this way?", offer to draft one: _"Want me to record this as an ADR?"_ Only when it clears three tests: it's hard to reverse, it's surprising without context, and it's the result of a real trade-off. Skip ephemeral or self-evident reasons.
sleeplessv