WAYS OF WORKING · APPLIED NINO CHAVEZ
A companion to the session demos — less "here's what happened," more "here's a technique, working." This one: how an AI agent draws a technical diagram that looks like your project and doesn't rot the next time the code changes.
Applied, not a receipt — everything here renders live in the page. Both diagrams below are real output, not screenshots of a claim.
→ or scroll to advance · ← to go back
02 THE PROBLEM
Technical diagrams fail two ways. The hand-drawn ones look great and go stale — the architecture moves, the picture doesn't, and now the docs lie. The generic ones stay current because they're cheap to redraw, but they look like every other flowchart and carry none of the product's identity.
An agent that reads your code can do better than both — if you let it pick the right tool for the diagram in front of it, instead of defaulting to one. What follows is the same system drawn two ways, so you can see the trade the choice actually makes.
03 APPROACH ONE
The agent reads the architecture, then draws it as a bespoke SVG in the project's own colors — here, a CLI tool's terminal palette. Every box and line is placed deliberately.
Hand-authored SVG · browse-tool architecture
What it buys
A layout you control to the pixel, a real motif, and colors pulled from the repo — so it reads as this project, not a template.
What it costs
Every coordinate is placed by hand and eyeballed. It doesn't scale past a small diagram, and it goes stale the moment the architecture moves. Reserve it for a surface someone judges.
04 APPROACH TWO
The same architecture, described in a few lines of Mermaid and themed to the same palette. It's text, so the agent writes it from reading the code, GitHub renders it inline, and updating it is a one-line diff.
Themed Mermaid · same system, ~80% of the look
flowchart LR subgraph CONTROL S([browse-start]) ==>|boots| C K([browse-stop]) -.->|kills| C end C[["Chrome · one long-lived process · :9222 + state file"]] NAVIGATE --> C INSPECT --> C EXTRACT --> C
The trade: auto-layout, so no traffic-light frame or hand-tuned grouping — but it stays current for free and needs no image file.
05 WHERE TEXT WINS OUTRIGHT
Hub-and-spoke is a near-tie. A process with a branch and a human-in-the-loop is where text pulls ahead — here, a real feedback-triage loop where an autonomy gate decides what an agent may auto-fix. Hand-placing this would be pure coordinate tedium for zero extra clarity.
Themed Mermaid · feedback triage loop
06 THE RULE
Both approaches are good. Neither is the default. One question picks the tool at the moment you draw: who reads this diagram, and how often does it change?
Reach for Mermaid when
Engineers are the audience and the diagram moves with the code — internal docs, ADRs, a request lifecycle. It should edit as a diff, and auto-layout is a feature, not a compromise.
Hand-author SVG when
A non-engineer judges the surface and the picture is stable — a README's first screen, a portal centerpiece. One or two diagrams, where the motif is the point.Audience × change-rate — decided per diagram, never defaulted.
07 HONEST LIMITS
The picker isn't a tool yet
Right now "choose per diagram" is a judgment I make by hand each time. The skill that would inspect the code and pick the tier automatically — /diagram — is designed, not built. This demo shows the technique, not a product.
Hand-SVG still doesn't scale
The bespoke approach is genuinely tedious past a handful of nodes, and I verified these renders in a local preview and here in this page — not yet on GitHub's own image proxy, where camo and dark-mode can still surprise you.
The inspect step is the hard part
Both approaches only look good because the agent read the real architecture first. Point either tool at a system it hasn't understood and you get a tidy diagram of the wrong thing.The drawing is easy. Reading the system is the work.
08 USE IT
The one rule to keep
Theme the diagram to the project, not to the tool. A shared init block of your colors makes every Mermaid diagram in a repo share one grammar — the same rule that keeps five README heroes from looking like one template.
Ask the agent for both
When you want a diagram, ask for the Mermaid version by default and the hand-SVG only for the surface a stranger judges. Make the agent name which it chose and why — that's the audience × change-rate call, made out loud.
Never draw blind
Have the agent inspect the code and state the structure back to you before it draws. If the description is wrong, the diagram will be wrong — beautifully.