SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsvisual-report

visual-report

Data & analytics

View repository

Updated 10-16 04:08

About this skill

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? Walk it with Explore subagents (subagent_type=Explore), one per independent area when the codebase has several; the writing stays with you. 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; a Mermaid diagram inside a tab or toggle follows the Interactivity recipe in HTML-REPORT.md. "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, with nothing on the console, in a page you never see. Re-read every Mermaid block for the known footguns (quote labels containing parentheses, colons, or HTML), then render the page headlessly (<skill-dir> is this skill's directory):

    uv run --no-project --with playwright python <skill-dir>/scripts/check_render.py <report.html>

    It judges what a reader sees: it waits for Mermaid to finish, opens tabs, toggles, and <details>, and ends PASS, FAIL, or BLOCKED.

    • FAIL: fix every line under problems (each failing diagram comes with its source line and Mermaid's error) and rerun.
    • BLOCKED means unverified, not passing: the environment kept the check from running. Apply the fix it prints, or hand the report over saying its render is unchecked.
    • PASS: read every screenshot it lists. diagram-<n>.png shows each diagram for legibility; page-<k>.png slices the page by viewport height, and is the only check on your hand-built CSS/SVG visuals (overlapping labels, arrows that miss their target, text spilling out of boxes). Fix what you see and rerun. Resolve each warnings entry, and name each unverified diagram when you hand over.

    Verify is done at PASS, with every screenshot read and every warning resolved.

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, rerunning the render check; 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.