Diagrams as Prompts

The Problem With Prose Handoffs

Prose feels clear when you write it. You're inside your own mental model. But when you hand it to an AI—or a teammate—all of a sudden the ambiguity surfaces. Dependencies weren't explicit. The sequence was wrong. Edge cases were invisible.

Here's a prose spec for a simple page build:

Sounds reasonable, right? But look at what you didn't specify:

• Does the nav need to be built before the cards?
• Can the cards be built in parallel, or do they depend on shared tokens?
• What if the hero depends on the nav's padding?
• Is responsive a constraint or a suggestion?

Now look at the same task as a diagram:

graph TD
    T[L0: Tokens] --> N[L1: Nav]
    T --> H[L1: Hero]
    T --> C[L1: Cards]
    N --> S[L2: Structure]
    H --> S
    C --> S
    S --> V[L3: Verify Responsive]

The diagram forces you to answer every question before you delegate. You see the dependencies. You see the layers. You see the build order. And when you give it to the AI, there's no ambiguity.

Diagrams as Specs

A mermaid flowchart replaces a multi-paragraph spec. It's terse, visual, and executable. The AI can read it. You can verify it. And it's version-controlable.

Example: A spec-driven workflow for feature development.

graph LR
    K["📋 KNOWLEDGE.md"] --> S["📄 SPEC.md"]
    S --> P["📋 PLAN.md"]
    P --> O["⚙️ OUTPUT"]
    O --> E["✅ EXECUTION"]
    E -->|Iterate| S

This diagram tells you:

• Start with what you know (KNOWLEDGE.md)
• Turn that into a spec (SPEC.md)
• Turn the spec into a plan (PLAN.md)
• Execute the plan and verify output
• If output doesn't match spec, iterate on the spec, not the code

Architecture Handoffs

When you need to coordinate multiple services or systems, a sequence diagram or architecture diagram replaces pages of documentation.

Example: A three-service architecture with explicit message flow.

sequenceDiagram
    Client->>API: POST /task
    API->>Queue: Enqueue task
    Queue->>Worker: Process task
    Worker->>Database: Save result
    Database->>Queue: Ack
    Queue->>API: Task complete
    API->>Client: Return result

Now the AI—and any engineer reading this—knows:

• The exact message passing order
• Which services talk to which
• Where synchronous vs. async boundaries are
• What happens when a service fails

Dependency Maps

If you can't draw the dependency graph, you don't understand the build order. And if you don't understand the build order, you're gambling that the AI does.

Example: A real build dependency graph.

graph TD
    CSS["CSS Tokens"] --> Nav["Nav Component"]
    CSS --> Hero["Hero Component"]
    CSS --> Card["Card Component"]
    Nav --> Page["Page Layout"]
    Hero --> Page
    Card --> Page
    Page --> Test["Integration Tests"]
    JS["JavaScript"] --> Test
    Test --> Build["Production Build"]

This diagram answers:

• What can be built in parallel? (Nav, Hero, Card all depend only on CSS)
• What's the critical path? (CSS → Page → Test → Build)
• What breaks if I skip a step? (You'll see it immediately)

Flow Analysis

Mermaid flows work for user journeys, data flows, and state machines. They make invisible paths visible.

Example: A visitor flow through a teaching site.

graph TD
    L["Landing Page"]
    L --> B["Browse Items"]
    B --> T1["Teaching Page"]
    B --> P["Paper PDF"]
    T1 --> T2["Other Teaching Pages"]
    T1 --> L
    P --> L
    T2 --> L

And a state machine for a task processor:

stateDiagram-v2
    [*] --> Idle
    Idle --> Running: task_enqueued
    Running --> Complete: success
    Running --> Failed: error
    Complete --> [*]
    Failed --> Idle: retry
    Failed --> [*]: max_retries

Flows expose edge cases you didn't think about. Where can the system get stuck? What transitions are missing? The diagram is the test suite.

The Universal Pattern

Every time you delegate work to an AI, follow this pattern:

1. Think. Don't write prose. Draw a diagram.
2. Audit. Does the diagram match your intent? Are there missing edges? Circular dependencies?
3. Delegate. Give ONLY the diagram to the AI. No long instructions.
4. Verify. Does the output match the diagram? If not, the AI either misread it or the diagram was wrong.

This is the contract. The diagram is the spec. Prose is optional. Code is the execution.

This pattern works for:

• Feature specs
• Build pipelines
• API contracts
• Data transformations
• System architecture
• User journeys

Real Examples

Here are three real diagrams I use in practice. Each one replaced pages of documentation.

Example 1: Site Build Lattice

This is a teaching site build. It shows layers of dependencies and which components can be built in parallel.

graph TD
    T["L0: Tokens"] --> N["L1: Nav"]
    T --> H["L1: Hero"]
    T --> C["L1: Cards"]
    N --> S["L2: Structure"]
    H --> S
    C --> S
    S --> V["L3: Verify"]

Used for: Handed this to an AI agent to build the site. The layers made the build order crystal clear. No ambiguity about what blocks what.

Example 2: Spec-Driven Workflow

This is the workflow I follow for every feature: Knowledge → Spec → Plan → Output → Execution.

graph LR
    K["KNOWLEDGE.md"] --> S["SPEC.md"]
    S --> P["PLAN.md"]
    P --> O["OUTPUT"]
    O --> E["EXECUTION"]

Used for: Pinning this above my terminal. When I'm tempted to jump to code without writing a spec, I see it and stop. The diagram is the guardrail.

Example 3: Visitor Flow

This is a teaching site's user journey. It shows how visitors move through the content and where they can return to the landing page.

graph TD
    L["Landing"]
    L --> B["Browse items"]
    B --> T1["Teaching page"]
    B --> P["Paper PDF"]
    T1 --> T2["Other teaching"]
    T1 --> L
    P --> L
    T2 --> L

Used for: Shared with a designer. They could see exactly how users move through the site without reading a single paragraph of documentation.