Agent Workflow

Ask an agent whether the diagram still matches the code

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

The question turns up in review, during onboarding, and thirty seconds before a customer call: is this picture still true. The last-modified date is not an answer, because a diagram edited yesterday can describe a system from March. An agent connected to a repo-linked project answers it precisely in one call, and it is worth knowing exactly how much that answer covers.

Try it free
6 min readFor anyone about to present a diagram they did not draw

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

141/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

One call, and what comes back

repo_status takes the project id of a repo-linked diagram and returns the link in full: the provider and repository, whether it tracks a branch or a tag and which one, the connection status, the commit sha the diagram reflects, the timestamp of the last sync and its status, any error from that sync, whether daily sync is on, and a plain-language freshness string.

The freshness string is deliberately coarse, because precision beyond this does not change any decision: never synced, synced in the last hour, synced a number of hours ago up to two days, then synced a number of days ago. What carries the weight is the commit sha, because it is the thing you can compare against git log and quote in a pull request description.

Only the owner of the repository connection can call it. An agent authenticated with someone else's key gets a clear refusal rather than a partial answer, which matters when several people in a workspace have their own keys.

repo_status(project_id: "prj_8fd2")

"Platform" tracks github acme/platform (branch main).
Sync: synced 31 hours ago, status ok, at commit 4f1c9a2b1d.
Daily sync is on.

> git log --oneline 4f1c9a2b1d..HEAD -- 'infra/**' 'services/**'
9b3e01c  feat(events): add consumer service
2c77ad4  chore: bump deps

Fresh is not the same as accurate

A sync that ran an hour ago proves the diagram reflects a recent commit. It does not prove the diagram shows the thing you are about to point at. Datadef does not read an entire repository: it selects up to 40 files and 250KB in priority order, starting with infrastructure as code, then containers and orchestration, then data definitions, then API specs, then CI configuration, then package manifests, then prose such as README files and docs/architecture. Files over 30KB are truncated with a visible marker, anything over 400KB is skipped outright, and node_modules, vendor, dist, .terraform, coverage and __pycache__ never contribute at all.

Per-class ceilings sit under that budget so one loud directory cannot take the whole thing. Under the architecture focus a repository contributes at most 16 Terraform files, 14 Kubernetes manifests, 10 CI workflows and 8 dependency manifests, but only 3 dbt models, 3 SQL files and 4 API definitions. A warehouse with four hundred models is represented by three of them, deliberately: that focus is about the system around the models. The content focus inverts the same numbers, and the first sync proposes one of the two by counting what is actually in the tree.

The consequence is worth saying out loud in a review: the diagram is grounded in those files. Architecture that lives only in a cloud console, a runtime configuration store, or a colleague's memory does not appear, however fresh the sync is.

So the honest sentence for an agent to produce is not "the diagram is correct". It is "the diagram reflects commit 4f1c9a2b at 06:12 today, generated from the infrastructure and service manifests in the repository". That phrasing tells a reader what to trust and what still needs a human.

Reading the answers that are not ok

A last sync status of failed comes with the error attached, and the previous diagram is left untouched, so the picture is old rather than broken. Read the error, fix the cause, then refresh.

A connection status of auth_failed means the provider rejected the token: revoked, expired, or missing the read scope. Reconnect with a fresh read-only token, a fine-grained GitHub token with Contents read-only, a GitLab token with read_api, or an Azure DevOps token with Code read. A status of not_found usually means a rename, a fine-grained token that does not include the repository, or a public repository that went private on a tokenless connection.

A sync stuck on running for more than ten minutes is considered stale and can simply be retried. And daily sync switched off is not a bug: somebody usually turned it off deliberately to protect hand edits from being replaced, which is exactly the case where an agent should ask before refreshing.

Asking the question without a repository connection

When the diagram is not repo-linked, an agent can still answer, just with less certainty. It reads the diagram structure with get_diagram, reads the parts of the codebase it judges relevant, and reports the differences it can see. That works, and it has two honest weaknesses: it costs a large amount of context on any real repository, and there is no commit anchor, so the answer cannot be re-checked later or quoted in a review.

It also compares only what it chose to read. A missing component in the agent's reading looks identical to a missing component in the system. A repository connection removes that ambiguity by fixing the corpus and the commit, which is why the freshness question is one of the strongest reasons to link the diagram to the repository rather than describing the system by hand.

Make the check cheap enough to run every time

A freshness check that needs a person to open a dashboard gets skipped. One tool call inside the session someone is already in does not. See how to detect stale diagrams for the checks that do not need an agent at all.

FAQ

How does an AI agent know whether an architecture diagram is out of date?

For a Datadef diagram linked to a repository, the agent calls repo_status, which returns the tracked branch or tag, the commit sha the diagram reflects, the last sync time and status, and whether daily sync is on. Comparing that commit against the current head of the branch gives an exact answer instead of an impression.

Does a recent sync mean the diagram is accurate?

It means the diagram reflects a recent commit of the files that were read. Datadef selects up to 40 files and 250KB in priority order, with per-class ceilings on top: under the architecture focus, 16 Terraform files but only 3 dbt models. Architecture that appears nowhere in the selected files is not drawn, so freshness is a statement about the source rather than a guarantee about the system.

What does it mean when the connection status is auth_failed?

The git provider rejected the stored token, usually because it was revoked, expired, or created without read access. Creating a new read-only token with the exact scope for the provider and reconnecting the repository fixes it. Diagrams keep their last synced content while the connection is broken.

Can an agent check freshness for a diagram that is not linked to a repository?

It can compare the diagram structure against the code it reads, but there is no commit anchor and no fixed corpus, so the answer cannot be verified later and depends on which files the agent chose to open. Linking the diagram to a branch or tag turns the question into a lookup.

Can someone else on the team run the freshness check?

Only the owner of the repository connection can call repo_status and repo_refresh for that link. Other members can open the diagram and see its sync state in the app, and an embedded diagram shows the current canvas to anyone with the link, with no account needed.