Visualize

Visualize

A picture earns its place only when it shows something words can't — shape, structure, direction, relationship, geometry. This skill produces ONE such picture, guarantees it is correct (the maker renders it and looks at it before returning), and drops it into the lesson so it renders inline in the Obsidian md-log file.

You are the creative director: decide the exact idea and distill it to its fewest carrying elements. A maker subagent does the authoring, rendering, visual verification, and saving, then returns a filename you embed.

When to visualize (and when not to)

This teaching system builds a dependency graph in the learner's head — axioms at the root, derived facts hanging off them. A visual is powerful exactly when it makes that structure (or a geometry) visible:

• Structure or relationship: dependencies, a system with parts and arrows, a flow/pipeline, a sequence of exchanges, a state machine, a tree/hierarchy, a comparison, a containment (inside vs outside).
• Spatial or geometric: coordinate geometry, a number line, vectors, a function's shape, a physical arrangement.

Do NOT visualize when prose or a single equation already carries it — a decorative diagram that just restates the neighboring sentence adds noise and a chance to be wrong. When in doubt, don't: a missing visual is cheaper than a false one.

Choose the maker

Two makers, discovered from .pi/agents/:

• mermaid-maker (default) — structural/relational: dependency graphs, flowcharts, sequence/state/ER/class diagrams, trees, mindmaps, timelines. Fits the dependency-graph pedagogy directly.
• svg-maker — spatial/geometric that Mermaid can't lay out: exact coordinates, geometry figures, number lines, vectors, plots, custom shapes.

Rule of thumb: nodes-and-edges / relationships → mermaid-maker; positions-and-shapes / geometry → svg-maker.

Brief the maker: one idea, fewest elements

The most common failure is cramming — every extra label makes the picture harder to read AND harder to lay out correctly. Prune first; for each element ask "if I delete this, is the idea still clear?" — if yes, delete it. Give the maker the concept AND the concrete elements you want (not a vague topic, not a long checklist). If your brief lists more than ~5–7 elements, cut it first.

• BAD: "make a diagram about how TCP works"
• GOOD: "graph TD: a node 'packet' at the top; arrows down to 'ordering' and 'retransmit on loss'; both arrows down into 'reliable stream'. No title. Show that reliability is built FROM packets, not alongside them."

Invoke

Dispatch the maker with the subagent tool:

subagent(agent="mermaid-maker", task="<your minimal, concrete brief>")
subagent(agent="svg-maker", task="<your minimal, concrete brief>")

The maker owns its purpose-built tools (write_*/edit_*/render_*): it authors the source, renders it to a PNG, looks at the PNG and iterates until it is correct and clean, publishes it into the vault with a unique filename, and returns:

RESULT:
filename: viz-<slug>-<timestamp>.png
path: <cwd>/viz/viz-<slug>-<timestamp>.png

If it returns RESULT: NONE, it couldn't make a correct picture of the brief — simplify, rethink, or decide the visual isn't worth it. Never hand-author or fake a diagram yourself; correctness depends on the maker's render-and-inspect loop.

Embed it in the lesson

Put the embed directly in your teaching reply, using Obsidian's wikilink embed with the returned filename (not the full path) and a display width:

![[viz-<slug>-<timestamp>.png|500]]

The md-log extension mirrors your reply text verbatim into the linked .md, and Obsidian resolves the embed by filename anywhere in the vault (the maker saves into the project's viz folder, which is inside the vault) — so it renders inline automatically. |500 is a good default; use larger for dense diagrams. Introduce the visual in a sentence, then let it carry the idea — don't narrate every element back in prose.

Why this is reliable

• The maker never returns a picture it hasn't looked at, so "renders fine but says something false" is caught before it reaches the learner.
• PNG embed means what the maker verified is pixel-identical to what the learner sees — no re-render drift.
• Unique filenames keep Obsidian's by-filename embed resolution unambiguous.

The makers render through the project's visual-tools extension (Mermaid via a bundled @mermaid-js/mermaid-cli + installed Chrome; SVG via rsvg-convert, fallback ImageMagick). You brief the maker and embed the filename it returns — you render nothing yourself.