explain-with-anim

Files (1)

• SKILL.md

SKILL.md (first lines)

# explain-with-anim

The user asked a question. Answer it with a picture and the words that walk
the picture — not a picture instead of an answer, and not a paragraph with
a decorative diagram after it. The figure is drawn from the code (or the
facts) by `vlmkit-anim`, checked, and delivered as a file; the prose follows
the figure beat by beat and names the things in it by their ids.

Read `explanatory-animation` for how to write and check a scene. This skill
is about **what to draw, from what, and how to explain with it**.

## First: does a picture help?

Draw when the answer has **things and relations** — four or more modules,
states, participants, steps — or an **order in time**, or a **before and
after**. Do not draw for a one-line answer, a single function's body, or a
question about a value. If in doubt, write the answer first; if it needs a
list of more than four named things that point at each other, draw them.

## Choose the picture from the question

| The user asks… | Draw | From |
|---|---|---|
| "How is this repo / package / directory structured?" | `kind: modules` — a module map, containers per area | `vlmkit-anim facts <dir> --depth 1 --out f.expect.json` (the import graph), then the map, then `check --expect f.expect.json`; for the whole workspace `vlmkit-anim repo --out <dir>` draws it and writes its own sheet |
| "How does a request / event / message flow through it?" | `modules` with a `sequence` that walks the path (`highlight`, `flow`), or `kind: sequence` when the participants and their calls are the point | the code path you read; the map from `facts`; each hop a beat with a caption saying why |
| "How does this algorithm / data structure work?" | the kind that owns it: `sort`, `array`, `tree`, `heap`, `stack`, `queue`, `list`, `matrix`, `graph` | the function's own steps; small concrete values (five to eight) so every beat is readable |
| "What states can this be in? What happens on X?" | `kind: state-machine` with a `trace` of the events that matter | the enum / reducer / status field and its transitions |
| "How do these services talk? What if one is slow / lost?" | `kind: distributed` (nodes, messages, a lost one) or `kind: sequence` (frames for retry / alt) | the protocol as implemented; the failure the user asked about as the trace |
| "Why does it go this way here?" (a decision) | `kind: flowchart` with the walked path | the branch conditions, as their labels |
| "What does this branch / PR change?" | `vlmkit-anim pr --base origin/main --out .vlmkit-anim/pr` — one beat per commit; or `vlmkit-anim diff before.json after.json` for two maps | git; `<name>.md` is paste-ready |
| "What is the schedule / what slipped?" | `kind: gantt` | the plan, the slips as `slip` ops |
| "The docs already have a mermaid diagram" | `vlmkit-anim import mermaid page.md --out scene.json`, then finish it | the diagram; read its `dropped / changed:` list |
| "Give me a D2 file" / "something I can paste in the README as ASCII" / the repo keeps `.d2` diagrams | `d2-diagram` — D2 text laid out by TALA, rendered in the terminal | the same `facts` sheet, drawn by hand into D2; say in the prose that nothing checks the D2 against the code |

One picture per question. Two aspects that both matter (structure and a
walk) are one `modules` scene with a `sequence`, or `kind: compose` — not
two files.

## Ground it in the source, not in memory

- A map of code is drawn from the code: `facts` for a directory, `repo` for
  the workspace, the import list or `package.json` files by hand when
  neither fits. Then `check --expect`. A map drawn from memory and not
  checked is a guess with a border round it.
- A walk is drawn from the path you read: cite the file and function each
  beat corresponds to in the caption or in the prose ("`handle()` in
  `router.ts` → `dispatch`").
- Anything you could not verify goes in the prose as "not drawn: …", never
  in the picture.

## Produce

```
1. write <name>.scene.json            in the repo's docs/ or .vlmkit-anim/, or the scratch dir if it is not to be kept
2. vlmkit-anim check <name>.scene.json [--expect <name>.expect.json]
3. vlmkit-anim layout <name>.scene.json               must report no issue; `why` when the canvas warning names a pair
4. vlmkit-anim still <name>.scene.json --out <name>.svg      a still (structure, a map, a state diagram)
   vlmkit-anim video <name>.scene.json --out <name>.gif --width 640   a walk (a request, an algorithm, a trace)
5. vlmkit-anim explain <name>.scene.json              the beats — this is the skeleton of your prose
```

Five rounds of edit → `check` at most. If it is not clean by then, deliver
the explanation in words, say the figure did not converge and which line
stopped it, and keep the scene file for the reader.

## Write the explanation

1. **One sentence of what the picture is** and what it was drawn from
   ("the packages under `packages/`, from their imports, 12 modules, 19
   dependencies").
2. **The beats, in order**, one short paragraph or bullet each, reworded
   from `explain` — say *why* at each step, not what moved. Name things by
   the ids in the picture so the reader can find them.
3. **What the picture leaves out** and where to read it (a file, a
   function, a config).
4. **The files**: the SVG / GIF path, the scene, the fact sheet.

Do not describe the picture's geometry ("on the left", "the blue box") —
layout is the compiler's and may move on the next edit. Say the id.

## Deliver

- In a chat: the prose, then the figure as a file the user can open
  (`SendUserFile` when available; otherwise the path). A GIF for a walk,
  an SVG for a structure.
- In a PR or issue: paste the `<name>.md` that `pr` / `repo` write, or the
  figure with the beats under it. If the repository already posts
  `vlmkit-anim pr --mermaid` on every PR (vlmkit's `pr-visual` workflow does), do not post a second one.
- In docs: a ```` ```vlm-anim ```` fence (the animation) or ```` ```vlm-anim still ````
  (the figure) with the scene inline, so the page stays checkable; or the
  SVG committed next to the page.

## Done condition

- `check` green (and `--expect` green when a sheet exists), `layout` clean.
- Every id named in the prose is in the picture, and every beat in the
  prose is a step in `explain`.
- The user can answer their own question from the figure alone; the prose
  says why each step is there.

## Anti-patterns

- **A figure after the answer, unreferenced.** If the prose never names an
  id from the picture, the picture is decoration; drop it or rewrite.
- **Drawing what you believe the structure is.** Run `facts` first. Two of
  five green module maps in one evaluation round were wrong about a real
  dependency.
- **Coordinates.** A scene with x / y is a drawing, not an explanation, and
  cannot be re-edited by the next reader. Use the kind that owns the things.
- **Twelve beats where four would do.** Pick the values and the trace that
  show the one mechanism the question is about.
- **Skipping `layout` because `check` was green.** Lines through labels are
  what a reader sees first.

From hasegama/pstack-agents, MIT.

More from hasegama/pstack-agents