Reviewing what the agent drew: the checklist that catches real mistakes

The invented component. Architecturally plausible, textually absent: a cache, a gateway, a message bus that the shape of the system suggests but no file declares. It survives casual review precisely because it looks like it belongs.

The reversed edge. Direction is where models are least reliable, and a reversed arrow between a service and a store or between a producer and a consumer changes the meaning of the whole picture while looking perfectly normal.

The missing boundary. Trust zones, network segments, and the line between what you run and what a vendor runs are rarely declared in one place, so they tend to be absent rather than wrong. Their absence is what makes a security reviewer distrust the diagram.

The stale name. A service renamed six months ago whose old label survives in a comment, a README, or a test fixture the agent happened to read.

The silent omission. A whole subsystem missing because it lives in another repository, is provisioned by a different team, or is integrated through a file upload nobody wrote code for.

Three of the five are found by one question: justify every node and every edge with a file path, or mark it as an assumption. Invented components and inferred edges collapse under it, and the list of things the agent could not determine is itself the most useful output of the review.

The canvas tools cover the rest of the mechanical checks. canvas_describe_canvas returns every node with its id, label, and group plus all connections and groups, which is a far better review artifact than a picture because it is greppable. canvas_validate_canvas reports orphans and overlaps. canvas_measure_canvas reports the size, which is how you catch the diagram that has grown past what anybody will read: the standard to measure against is 12 to 20 nodes with no more edges than nodes, and 25 to 40 only when depth was the point. Above that, canvas_suggest_simplifications names which nodes are candidates to collapse, so trimming becomes a proposal to accept or reject rather than an argument with a layout.

Review pass, before I look at it:

  1. canvas_describe_canvas - list nodes, groups, edges
  2. For each node and edge: the file that justifies it,
     or ASSUMPTION
  3. canvas_validate_canvas - orphans, overlaps
  4. What did you find in the repo that is NOT on the canvas,
     and why did you leave it out

Question one: is this the architecture we intend, or the architecture we have. Both are legitimate subjects for a diagram and they are different diagrams, and a generated one is always the second.

Question two: what is missing that only you would know. The vendor integration with no code, the manual approval, the service another team runs, the path that exists but is deprecated. This is where the review earns its time.

Question three: does the grouping mean something. An agent groups by what it can see, usually directory layout or naming. A human groups by domain, ownership, or trust boundary, and that regrouping is often the single change that makes a diagram legible. Do it on the canvas and it stays done.

Record what the diagram was reviewed against, which means the commit or tag, and the date. A review with no anchor cannot tell anyone later whether it still applies.

Then avoid re-reviewing from scratch. If the diagram is generated from connected source, subsequent regenerations change only what the source changed, node identity stays stable, and hand-moved positions are kept, so the next review is a diff rather than a repeat. Publish the reviewed version as a live embed so the reviewed copy is the copy everyone sees.

• What an agent can and cannot infer from code
• Keeping an AI-generated diagram trustworthy
• The canvas: edit what the agent drew
• Documentation audit checklist