vis

Files (8)

• SKILL.md
• build.mjs
• cookbook.md
• legend.html
• style.css
• marked.min.js · vendor/
• mermaid.min.js · vendor/
• vocab.mmd

SKILL.md (first lines)

You are producing a document that gets an engineer ready to add features to this repo after one read.
No questions to the user. Work through every phase in order. Nothing else.

The deliverable: `~/Desktop/<repo>-vis.pdf`, A4 landscape, 12 pages plus 2 per main feature, built from Markdown with
Mermaid diagrams by `$VIS/build.mjs`, where `$VIS` is the directory holding this SKILL.md
(normally `~/.claude/skills/vis`). The information lives on the diagrams: box names,
role lines, paths, and labelled arrows. Prose is short and in simple words.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PHASE 1 — SETUP
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Repo root: `git rev-parse --show-toplevel` (fall back to the current directory).
   Repo name: basename of that path.
2. Work dir: `WORK=$(mktemp -d -t vis)`. All intermediate files go there.
   Output: `OUT=~/Desktop/<repo>-vis.pdf`. If it exists, overwrite it.
3. Read `$VIS/cookbook.md` now. Every diagram you write must follow a shape from it.
   Do not invent Mermaid syntax. Do not write classDef lines; the build injects the vocabulary.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PHASE 2 — STUDY, THEN EXTRACT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Invoke the `study` skill first. This is mandatory.

Then get the facts a diagram needs. Use deterministic tools for edges; use your own reading only
to name and group things. Never install anything (no brew, pip, npm -g, cargo install, go install).
`npx --yes` is allowed because it installs nothing permanently. Record what ran and what was missing.

Size and language:
  - `scc --format json .` if `scc` exists, else `find` + `wc -l` per top-level folder.
  - The language with the most lines decides which extractor to try.

Edges (imports, calls), first one that applies and is available:
  - JS/TS:     `npx --yes dependency-cruiser --no-config --output-type json src > $WORK/deps.json`
  - Python:    `pydeps <pkg> --show-deps --no-output > $WORK/deps.json`; `pyreverse -o mmd -p <name> <pkg>` if pylint exists
  - Go:        `goda graph "./...:all" > $WORK/deps.dot`
  - Rust:      `cargo modules dependencies --lib > $WORK/deps.dot`
  - Java:      `jdeps -verbose:class -dotoutput $WORK/jdeps <jar or classes dir>`
  - Any:       if nothing above exists, read entry points, config, and imports by hand with grep.

Always by hand:
  - Technologies: every manifest and build file (package.json, Cargo.toml, pyproject, go.mod,
    depends/, Dockerfile, CI workflows). For each: what it does for THIS project.
  - Entry points: main files, CLI commands, HTTP routes, cron or job definitions, message consumers.
  - Inputs: what comes in from outside (requests, files, peers, queues, APIs, env or config).
  - Outputs and artifacts: what goes out or is produced (responses, files written, emails, DB rows,
    build outputs, logs). Name the real folder, file, or table.
  - Load facts, only from evidence: rates or intervals in constants and docs, data sizes in docs,
    thread and worker counts in code, what each request reads versus writes. Where the repo says
    nothing, the answer is "not stated in repo". Never invent a number.
  - External systems: databases, queues, third-party APIs, other services. Black boxes only.
  - Stateful things: any entity with 4 or more named states (enum, status column, state machine).
  - Threads, workers, processes, queues: how work is split at runtime.
  - `lessons/` folder if present: read it; it tells you where things went wrong before.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PHASE 3 — BUILD THE CAST (ONE MODEL, MANY VIEWS)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Write `$WORK/cast.md`: one table that every diagram is drawn from. Columns:

  | Name (plain words) | Kind | Tier | Path | Lines | Role (3 to 5 words) | Takes in | Gives out | Talks to |

Kind is one of: person, external, entry, core, worker, store, queue, artifact.
Tier is major, normal, or minor: major = on the critical path or the biggest part; minor = small
helper or rarely touched. Stores get their tier from how central they are to the main flow.
Rules:
  - Every row with kind entry/core/worker/store/queue/artifact has a real path that exists. Check it.
  - Names are everyday words. "Scorer", not "ScoringServiceImpl". Keep the same name everywhere.
  - At most 14 rows inside the repo. Group small folders into the part they serve. Diagrams never
    introduce a box that is not in the cast.
  - Pick the ONE critical path: the thing the system exists to do. It becomes the sequence page and
    the thick arrows on the architecture page.
  - Pick 3 to 5 columns for the layers page: self-contained vertical slices (for example Network,
    Validation, Storage, Wallet, API), each owning 2 to 4 cast rows.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PHASE 4 — THE VISUAL VOCABULARY (fixed, every page)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

One shape and one colour per kind, on every page. The build injects the colours; you assign classes.

  person      stadium        `you([You<br/><small>role</small>])`                          class person
  external    hexagon        `x{{Name<br/><small>what it is</small>}}`                    class external
  entry       parallelogram  `r[/Name<br/>role<br/><small>path</small>/]`                 class entry
  core        rectangle      `c[Name<br/>role<br/><small>path</small>]`                    class core
  worker      procs          `w@{ shape: procs, label: "Name<br/>role<br/><small>path</small>" }`   class worker
  store       disk           `s@{ shape: lin-cyl, label: "Name<br/>role<br/><small>path</small>" }` class store
  queue       das            `q@{ shape: das, label: "Name<br/><small>path</small>" }`     class queue
  artifact    doc            `f@{ shape: doc, label: "name" }`                             class artifact
  tier        second class   `class a,b major` · `class c minor` (normal is the default)

Box text: line 1 the name, line 2 the role in three to five words, line 3 the path in `<small>`.
People and outside systems have no path.

Every arrow is labelled: verb plus object, then format or protocol when known. Direction is the
direction the data moves. `-->|sends blocks, TCP|` data or call · `-.->|announces new block|`
event or async · `==>|hands the block to|` the one critical path. Unlabelled arrows are a defect.
On the architecture page keep labels to two or three words, and never draw an arrow from deep
inside the system back to a person or outside system: it closes a cycle and the diagram turns
tall and narrow. Say that fact in the box's role line instead. People and outside systems only
send arrows in, or receive them from a way-in or an event feed.
A flow longer than seven boxes in a line becomes a thin strip: split it into two `short` fences
on the same page.

SPACING RULE, no overlaps anywhere: no text may touch or cross a box border, another label, or
an arrow. The build already spaces nodes and ranks generously; what you control is the amount of
text. Box text: at most three lines, each at most five words, plus the small path line. Arrow
labels: at most four words on flowcharts, two or three on block grids. Grid cells (layers,
inputs and outputs): at most two short lines plus the path, no `major` class. Sequence messages:
at most eight words, they wrap automatically. Sequence participants: the name, then on the
second line the file BASENAME only (invite.ts, not the full path), or the participant boxes
overlap each other. If a label still collides, shorten it, move the
fact into the box's role line, add a `space` cell, or split the diagram in two `short` fences.

The legend strip with these shapes, the three arrow styles, and the zoom breadcrumb is added by
the build to every diagram page. Declare the zoom level on the fence: `level=1` system,
`level=2` parts, `level=3` inside.

From Banksy-said-hi/claude-skills, MIT.

More from Banksy-said-hi/claude-skills