Keeping an AI-generated diagram trustworthy after the first draft

A diagram is trusted when a reader who finds something surprising assumes the diagram is right and their memory is wrong. That assumption is earned slowly and lost in one incident, when somebody follows the picture into a service that was renamed a quarter ago.

Which means the first draft being 90 percent right is not the interesting number. The interesting number is how long the picture stays 90 percent right without anyone doing anything, and what happens on the day it stops.

There is a real difference between a diagram generated from a paragraph somebody typed and a diagram generated from parsed source. The first is a model rendering a description; the second is a rendering of declarations. Both can be useful, and they deserve different levels of belief.

Where the source is declared, prefer the parse. A Terraform repository parses into resources, modules, references, and per-environment counts, none of which is a model output, and the doc written around it is grounded in that parsed model rather than free-written. What a model contributes is arrangement and prose, not the list of what exists.

The module reference table at the end of that document goes further: it is composed in code, never by the model, so every module name, source string and resource count in it is parsed rather than written. A registry module the parse cannot expand reads "external" in its Resources cell instead of a number nobody could compute.

Then record the provenance where the reader will see it: which repository, which branch or tag, which commit, and when. A diagram carrying that line invites a reader to check it. A diagram carrying nothing invites a reader to believe it forever.

repo_status -> what a reader needs to see:

  repository   github.com/acme/platform
  tracking     tag v4.2.0
  reflects     commit 8f1c2ab
  last synced  3 hours ago
  daily sync   on

Exported images are how a correct diagram becomes several diagrams of different ages. The PNG in the wiki, the one pasted in the deck, the one attached to an old ticket: each froze on the day it was exported and none of them says so.

A live embed is one markdown line that renders the current canvas wherever markdown renders images, in a README, Notion, or Confluence, with no account needed to view it. When the canvas changes, every copy changes, because there is only one copy. Keep image export for slides, where a frozen picture is what you actually want.

Trust survives on the existence of a failure mode. If nothing can report that the diagram is behind, then nobody finds out until it embarrasses someone. The check is simple: compare the commit the diagram reflects to the head of the branch it tracks, and treat a large gap as a problem rather than as normal.

Two mechanisms make that cheap. A connected repository regenerates daily and skips any commit whose parsed structure hashes to the same value as the last one, so the gap you are looking at means real drift rather than commit noise. And an agent in a session can ask for the status before a design review and refresh it when it is behind, which turns the check into a habit attached to a meeting rather than a policy nobody follows.

The sync also measures its own honesty. Each regeneration records the share of the previous diagram that survived it, as the percentage of node ids present before that are still present after. A low number on a large source change is expected. A low number on a one-line change is the signal that the picture recomposed itself instead of updating, which is the failure that quietly costs a generated diagram its readers.

• Reviewing what the agent drew
• What an agent can and cannot infer from code
• Live embeds: one line, always current
• What makes documentation trustworthy
• Repo to diagram: how repository sync works