Circuitry Logo
Circuitry
Open Circuitry

Tips for Working with Diagrams

Ask plainly. Timings, observations, recommendations, actors, lanes and frames are things these diagrams are built to hold, so you can name them and the agent knows what you mean.

Drawing from what actually happened

Draw a real run from its logs. Give each part its own log, run the test, then: "Take these logs and draw the run as a sequence diagram."

Update the diagram instead of redrawing it. "Take my logs and update the sequence diagram with timings, observations and recommendations."

Ask for measured numbers, not plausible ones. "Use what the log says — put 'not observed' where it isn't there."

Compare two runs. Same scenario, different conditions, named diagrams side by side. The step where they diverge is the fault.

Keeping a diagram worth trusting

Name them. A named diagram is updated by name, so "Dial on wifi" and "Dial on 5G" can sit on one canvas.

Ask for new diagrams in the same document. "Add this as a new diagram on the same canvas." The system builds up in one place, and one diagram per change leaves you before and after as it improves.

Have it read the diagram back before it edits. It may have moved since — by you, or by an earlier session.

Stamp a diagram of code with its sources. "Record the files and the commit you read." It already records when it was drawn — the files let it tell you the code has moved since.

Ask it to bring the diagram up to date. "Check this diagram still matches the code, and fix what has changed." It has the date it was drawn and the files it came from.

Ask it to think in Mermaid. "Keep a Mermaid diagram in the docs, and in a comment at the top of the file." Plain text, so it diffs a line at a time and travels in the commit.

Saying what the picture cannot

Put the reason in the box's Notes. Kept out of the drawing but travels with the box — so it is also where you leave instructions for the agent.

Say what you have open. "I have the sequence diagram open — why does the retry happen before the check?"

Working with other people

Walk the team through it live. Share puts the real diagram on everyone's own screen — they can point at it, draw on it and edit alongside you, not squint at a screen share.

Related