Flowcharts

Draw what a system does — each step, each decision, each loop — and have the agent draw how the code actually does it, so you can compare what you meant with what was built.

A sequence diagram answers who talks to whom, in what order. A flowchart answers a different question: what happens next, and which way does it branch? Both are ways to describe how a system should work, and both are much easier to check than a paragraph of prose.

The flowchart has one extra use. Ask the agent to draw how a piece of code actually works, and it reads the code and draws that — every if a decision, every early return an end, every loop an arrow going back. Put that next to the flowchart of how it was supposed to work, and the difference is the thing to talk about.

Tap to enlarge

Green pills start and end it, blue boxes are steps, orange diamonds are decisions, and every branch is labelled. The two loops — back to triage, and back to engineering with more detail — run down the sides, clear of the boxes.

What's on a flowchart

Shapes, by what they mean

A decision diamond wraps its text to the diamond's shape — longer lines across the wide middle, shorter ones towards the points — and grows to fit it.

Arrows

An arrow shows what happens next. An arrow out of a decision carries a short label — yes, no, retry — so you can read which answer goes where. A dashed arrow is for illustration only, and a thick one is for emphasis.

An arrow's label takes the colour of the box it comes from, so a decision's yes and no are orange like the decision.

Where two straight arrows cross, the flatter one hops over the other with a small jump, so a crossing never looks like a join.

Colours carry meaning

A flowchart the agent draws is coloured by what each shape means:

• Soft blue — steps (and sub-processes)
• Green — start and end
• Orange — decisions
• Teal — data: cylinders, input and output, documents

Two colours are kept for one meaning each and are never used just for decoration: red means an alert or an error, and grey means disabled. So a red box always means something is wrong there, and a grey one is switched off.

All the colours are soft, filled solid with no outline, and chosen to stay readable in both light and dark themes.

Title and key

A flowchart can carry a title above it, with a line underneath saying what it is — "a proposal for discussion", or "today's code". Beside it, a key box explains itself to someone who wasn't in the conversation:

• Key — what each colour means, with a swatch
• Terms — a short definition for any word the reader may not know
• Observations and Recommendations — what was found, and what to change

Ask the agent to draw one

Ask in plain words and the agent draws it on the canvas you have open:

• "Draw how checkout works, from the code."
• "Map the process for approving a refund."
• "Mark the step where it fails." — that step turns red.
• "Add a key for the colours, and explain the jargon."
• "Update the diagram — I renamed a step."

From the code. Asked to draw real code, the agent reads the function top to bottom: each if, else or switch becomes a decision with its branches labelled, each early return or error becomes an end, each loop becomes an arrow back, and each call into another part of the code becomes a sub-process box. It keeps one box per step you care about, not one per line.

It says what it drew from. The agent notes which files it read and which version of the code, and the diagram itself records when it was drawn and when it was last updated. When the code moves on, you can tell the diagram is stale — ask "is this diagram still current?" and it re-reads the code and fixes what has moved.

Re-sending updates it in place. The title is the diagram's name. Ask for a change and the same diagram is updated — not drawn again beside it. A box you dragged somewhere keeps its place; the rest follow the new layout. Ask for a diagram with a different title and it is drawn as a second diagram on the same canvas, which is how you put "as designed" next to "as built".

It reads your changes. The agent reads the diagram back from the canvas every time it looks, so it sees your renames and your dragging — and the work of an earlier session — rather than a copy it remembers.

Laid out for you

When the agent draws a flowchart, it is laid out automatically:

• Arrows go around boxes, not through them, and two arrows don't run on top of each other.
• A decision's answers leave by different sides, so you can see where each one goes.
• A loop runs down the side with the fewest boxes in the way.
• Two arrows may cross where that avoids a kink or an overlap — a crossing is easier to read than a tangle.

Then it is yours to adjust:

• Drag a box and it stays exactly where you drop it. Its arrows are then re-routed around the other boxes by the same rules as the layout, and the move is one undo step.
• Drag the title (or the key) and the whole diagram moves with it — boxes, title, key and arrows.
• One drag is one undo. Moving the whole diagram and then pressing undo puts all of it back.
• Double-click a box (or double-tap it) to rename it.

Draw one by hand

1. Choose Flowchart from the new-document menu. It opens a canvas with the node palette already showing the Flow Templates — the flowchart shapes.
2. Drag shapes onto the canvas: Start, End, Process, Decision, Data, Database, Document, Manual, I/O and more.
3. Connect them by dragging from one shape's edge to another — see Adding & Connecting Nodes.

The shapes are also on any workflow or whiteboard canvas: click the Flow tile in the node palette to open the same templates, and ← Back to return.

The workflow If node is drawn as the same orange decision diamond, so a workflow reads like a flowchart.

A flowchart is a workflow underneath, so the same canvas can become one that runs. The first node you add that isn't a flow shape — code, an AI agent, a sheet — renames the document from Flowchart to Workflow, unless you have already given it your own name.

Related

• Sequence Diagrams — who talks to whom, in what order
• Class Diagrams & Data Models — what exists and how it is built
• Tips for working with diagrams — drawing from what actually happened, and keeping a diagram worth trusting
• Sketch to Diagram — hand-drawn sketches become diagrams
• Workflows Overview — the canvas these are drawn on