explain-with-anim

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

One sentence of what the picture is and what it was drawn from ("the packages under packages/, from their imports, 12 modules, 19 dependencies").
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.
What the picture leaves out and where to read it (a file, a function, a config).
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.