---
name: interactive-diagram
description: Turn a codebase, a system description, a process or a database schema into one self-contained interactive HTML diagram (architecture, workflow, data flow, lifecycle, ERD, sequence, class, tree, timeline or waterfall) where every box and arrow cites the file and line or the words it came from, anything inferred is drawn dashed as an assumption, and each cited line is checked against the repository before the page is written. Laid out automatically, opens offline with no CDN, and exports SVG, PNG and Mermaid. Use when the user asks to "visualize", "map" or "make an interactive diagram of" a repo, a request path, a pipeline, an approval process, a set of tables, an incident's events or a slow trace, or wants a diagram they can click through and share as one file.
---

# interactive-diagram

**The rule: nothing goes on the map that the material doesn't show.** A diagram is trusted
more than prose, so an invented box misleads more than an invented sentence. Asked to draw a
repo, the agent's habit is to draw the system such repos usually have: a load balancer, an
auth service, the Kafka the README says is planned. Here every part and every connection
either cites where it came from (`src/api.py:40-52`, or the person's own words) or is drawn
dashed and listed as an assumption. The script checks each cited file and line before it
writes the page, and refuses a spec that cites a line that isn't there.

Two things follow:

- **One question per map.** Draw what answers the question asked ("what happens when an order
  is placed"), not every module in the repo. A part that doesn't help answer it stays off,
  and the reply says in one line what was left out.
- **You write the meaning; the script does the layout.** Never write coordinates. List the
  parts and connections in the order a reader meets them, and the script places them, routes
  every arrow around the boxes, draws groups as boxes that don't overlap, and wraps a long
  flow onto rows so its text stays readable.

## How to respond

1. **Name the question and pick the type.** One sentence: what will the reader understand
   after looking? Then the type:

   | Type | For |
   |---|---|
   | `architecture` | What a system is made of and what talks to what |
   | `dataflow` | Where data or money or documents go, stage by stage |
   | `workflow` | A process with steps, decisions and hand-offs, technical or everyday |
   | `lifecycle` | The states something moves through and what moves it |
   | `erd` | Tables, their columns and keys, and how they reference each other |
   | `sequence` | Who calls whom, in order, for one request or exchange |
   | `class` | Types, their members, and inherits, implements, composition and the rest |
   | `tree` | What contains what, one parent each: a repo's folders, a capability breakdown, an org |
   | `timeline` | When things happened, on a clock, one lane per source: an incident, a release history |
   | `waterfall` | Where the time went in one request or run: spans to scale, nested, with the critical path |

2. **Gather the facts, with where each came from.**
   - **A repository:** trace the one path the question is about. Read the entry point, follow
     the calls, and for each part and each arrow note the file and lines that show it. Add a
     few characters from those lines after `#` (`src/api.py:12#stripe.PaymentIntent`) so a
     wrong line number is caught. Config and README files show intent, not behaviour: a
     service the README mentions but no code calls is left off, or drawn as an assumption with
     the README as its only evidence and said so in the reply.
   - **A description:** cite the person's words: `"user: anything over ten days goes to HR"`.
   - **Something you believe but can't point to** (who calls the API, what the worker does
     next): `"assumed": true`. It is drawn dashed and listed. Leave it off if it doesn't help
     answer the question.
   - **Times, for a timeline:** write each time as its source gives it, with its offset when
     sources differ (`2026-10-11T03:41:00Z`, `2026-10-10T22:41-05:00`); the script puts them
     on one clock. A time the source is unsure of gets `"approx": true`. Link two events
     (`caused`, `fixed`) only when the material says one led to the other; an event that came
     after another did not necessarily follow from it.
   - **Spans, for a waterfall:** copy each span's start and end from the trace as they are,
     including one that ends after its parent; the script flags it.
   - **The person's guesses or questions** ("is it the north fetch?", "was it the vacuum?"):
     answer each in `answers`, with evidence, or as an assumption when the material is silent.
     They appear as a table at the top of the page.

3. **Write the spec** as JSON next to where the page will go. The full shape, every kind and
   the ERD and sequence fields are in [`reference.md`](reference.md). The essentials:

   ```json
   {"type": "architecture", "title": "What a checkout request touches",
    "question": "What happens when a shopper checks out?",
    "summary": "One or two sentences: the takeaway a reader should leave with.",
    "groups": [{"id": "vpc", "label": "Private VPC"}],
    "nodes": [{"id": "api", "label": "Checkout API", "kind": "service", "group": "vpc",
               "note": "FastAPI", "evidence": ["src/api.py:8-14#def checkout"]}],
    "edges": [{"from": "api", "to": "db", "label": "insert order", "evidence": ["src/api.py:13"]}],
    "story": [{"text": "The API checks the cache first.", "edges": ["e2"]}]}
   ```

   Labels are a few words; detail goes in `note` (shown on the box) or `detail` (shown when
   clicked). For a timeline, set `timezone` to the zone the reader works in. Write `summary`
   last, from what the script computed: a summary that says "over four hours" beside a
   computed 3h 37m is the kind of slip the page exists to prevent. Add a `story` of three to seven steps when the map has a main path worth walking.

4. **Build it.** With a repository, always pass `--repo-root` so the citations are checked.
   For a waterfall or a timeline the script also prints what it computed (each span's own
   time, which spans overlap, the longest quiet stretch, time zones): use those numbers in the
   reply as they are, and never add up durations yourself.

   ```bash
   # Claude Code
   python3 "${CLAUDE_SKILL_DIR}/scripts/build_diagram.py" diagram.json -o diagram.html --repo-root .
   # Other IDEs (from the skill folder)
   python3 scripts/build_diagram.py diagram.json -o diagram.html --repo-root .
   ```

   Errors list the item, what is wrong and the fix, and nothing is written until they're gone.
   Fix the spec, never the evidence: a citation the check can't find is wrong, so find the
   right lines or mark the item assumed. Add `--mermaid diagram.mmd` for a version to paste
   into a README, and `--compare old.json` to show what a change adds, removes and alters.

5. **Lead the reply with the map.** The script prints a titled link to the page. Put it at the
   top, then the takeaway in one or two sentences, then one line each for what is drawn as an
   assumption and what was left out, and last how many citations were checked:

   > **What a checkout request touches** (the script's link line: the title, linked to the page)
   >
   > The API charges Stripe before it records the order, and a worker books the courier later.
   > Assumed: the shopper's browser (no client in this repo). Left out: the products table's
   > other readers. 22 of 22 citations checked.

   Keep the spec beside the page so the map can be rebuilt after the code changes. At most one
   short line about the build may come before the link; no recap of commands or layout.

6. **When the script can't run** (no `python3`), give the Mermaid version in the reply, with
   assumptions marked, and say that the interactive page needs Python 3.

This is a non-interactive skill: don't stop to ask. With too little to draw from, draw what
you have, mark the rest as assumptions, and say in the reply what would settle them.

**Sharing:** the page shows the cited lines when a part is clicked. Files that hold secrets
(`.env`, keys, credential files) are never shown and secret-looking lines are masked, but
don't cite them in the first place, and read the page before it leaves the team.

## Quality bar

- **Every part and connection cites its source or is drawn as an assumption.** No exceptions
  for the "obvious" ones.
- **Every file citation was checked** against the repository, with the count in the reply.
- **Nothing on the map comes only from a README, a plan or what such systems usually have.**
- **The map answers one stated question,** and what was left out is said.
- **One HTML file that works offline:** no CDN, no external fonts, no network requests.
- **The link and the takeaway lead the reply,** with at most one short line about the build
  before them and no account of how it was made.

## When to use this skill

- ✅ "Map what happens when an order is placed in this repo, as something I can click through"
- ✅ "Turn this description of our approval process into an interactive flowchart for the team"
- ✅ "Give me an interactive ERD of schema.sql"
- ✅ "Show what this branch changes in the architecture" (two specs and `--compare`)

## When NOT to use this skill

- ❌ A Mermaid, PlantUML or C4 diagram to paste into a doc — use `architecture-diagrams`
- ❌ An as-is architecture write-up in C4 levels from infrastructure files — use `reverse-architecture`
- ❌ Fixing or rendering an existing Mermaid diagram; the agent does that well on its own, with `npx @mermaid-js/mermaid-cli` for images
- ❌ Charts of numbers, dashboards or metrics — this draws structure, not data

## Anti-patterns to avoid

- ❌ **The usual architecture.** A load balancer, CDN or auth service drawn because systems
  like this have one.
- ❌ **README as evidence of behaviour.** "We use Kafka" in a README is a plan until code
  calls it.
- ❌ **Deleting evidence to pass the check.** A failed citation means the line is wrong or
  the part is an assumption.
- ❌ **Everything in the repo.** Forty boxes answer no question.
- ❌ **Hand-placed coordinates** or a hand-written SVG instead of the script.
- ❌ **A page that loads a library from a CDN.** It breaks offline and leaks the viewer's IP.