Agent Workflow

Diagram a refactor before the code: reviewing a proposal you can see

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

Plan first, then code, is now the default way to work with an agent, and the plans are convincing. They are also prose, and prose hides exactly the property a refactor lives or dies by: the shape of the dependency graph afterwards. A plan that reads well can describe a design where one module ends up talking to everything. Two pictures, current and proposed, make that visible in the ten seconds before anyone writes code.

Try it free
7 min readFor reviewers of agent-written refactor and migration plans

See it as a diagram

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

160/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

What a written plan does not show

A refactor plan lists steps. Extract this package, move that handler, introduce an interface here. Read in order, each step is defensible. What no ordered list conveys is the end state as a graph: how many inbound edges the new shared module has, whether the dependency direction between two layers just inverted, whether a component that was leaf-level is now on every path.

Those are the properties that decide whether the refactor is worth doing, and they are the ones a reader reconstructs badly from text. The reconstruction is also where reviewers quietly give up and approve, because holding fifteen components and their edges in your head while reading step nine is genuinely hard.

A picture moves the cost from the reviewer to the drawing. It also makes disagreement concrete: instead of "I am not sure about the boundaries", the conversation becomes "why does the scheduler reach into the store directly".

Draw the target beside the current state

The proposed diagram is only useful next to an honest current-state diagram, and the current one should not come from the same agent that wrote the plan. If both halves come from one reading of the code, a misunderstanding appears identically in both, and the comparison confirms nothing.

The cheapest independent baseline is a repository-linked diagram generated from the default branch. It reads the infrastructure code, manifests, schemas, API specs and CI configuration directly, so it reflects what the repository declares rather than what the agent believes. Have the agent draw only the target state, and put it beside that.

Keep the proposal in its own diagram. A repo-linked project regenerates from source, and the timing is worse than it first sounds. A sync whose structure fingerprint has not moved skips generation entirely, so a target state drawn into a linked project survives every cosmetic commit and is then wiped without warning by the first structural one, which might be three weeks later. Until that moment it is indistinguishable from reality for anyone who opens the link. create_blank_diagram gives the agent an empty canvas to build the target on, and it spends no credit because no Datadef generation runs.

# current state, generated from the branch, not from the plan
repo_status(project_id: "prj_8fd2")   -> commit 4f1c9a2b1d, synced today

# proposal, in its own diagram so no sync can overwrite it
create_blank_diagram(name: "Billing split: target state")
canvas_group_nodes(...)    # the modules after the split
canvas_connect_nodes(...)  # every edge that crosses a boundary
canvas_validate_canvas(...)

Review the picture against the repository

Read the target diagram for four things. Edges that cross a boundary the plan claims to establish. Components with an unexplained increase in fan-in, which are the future bottleneck. Datastores with more than one writer, which is the migration risk nobody costs correctly. And components that appear in the target and nowhere in the current-state diagram, because a new box in a refactor plan is either an omission from the baseline or work that was not in the estimate.

Then check the target against the code, not against the plan. Ask the agent to name the file or module behind each node in the current-state half. Anything it cannot point at is a guess, and guesses in the baseline invalidate the comparison. On a Terraform baseline that check is mechanical rather than a matter of trust, because node ids are derived from the resource address: the workspace node in the picture is a named resource in a named module in a named file, and the generated architecture document carries the module reference table behind every rolled-up node.

The judgment that stays human is the one about time: whether this refactor is worth doing now, what it costs to run both shapes during the migration, and which team owns the halves afterwards. A diagram makes those conversations shorter, it does not settle them.

What to do with the proposal once it lands

When the refactor ships, the target diagram stops being a proposal and becomes a claim about the system, which is the moment it starts lying. Retire it. Publish a version of it as the record attached to the decision, then let the repository-linked diagram of the default branch carry the current state.

That handover is the cheapest documentation habit available around agent work: the proposal diagram documents intent at a point in time and never changes, and the synced diagram documents reality and never stops changing. Trouble starts when one artifact is asked to do both jobs.

One diagram, one job

A proposal that stays editable becomes an unlabelled half-truth within a month. Keep proposals as published versions and let the synced project own the present. See ADRs versus architecture diagrams.

FAQ

Why draw a refactor before writing the code?

Because the property that decides whether a refactor is worth doing is the shape of the dependency graph afterwards, and an ordered list of steps does not show it. A target-state diagram exposes fan-in, inverted dependencies and datastores with several writers in seconds, while a reader reconstructing the same thing from prose usually gives up.

Should the agent draw both the current and the target state?

The target, yes. The current state is more trustworthy when it comes from an independent read, such as a diagram generated directly from the repository, because a misunderstanding in the agent reading of the code would otherwise appear in both halves and cancel out in the comparison.

Where should a proposed architecture diagram live?

In its own diagram, not in the project linked to the repository. A linked project regenerates from source on each sync, so a proposal drawn into it is replaced at the next sync and, until then, looks like the current architecture to anyone who opens the link.

What should a reviewer look for in a target-state diagram?

Edges that cross the boundaries the plan claims to draw, components whose inbound edge count jumps, datastores that end up with more than one writer, and boxes that exist in the target but nowhere in the current state. Each is a question the plan usually does not answer.

What happens to the proposal diagram after the refactor ships?

Publish it as a fixed version attached to the decision record and let the repository-linked diagram carry the current state. A proposal left editable turns into an unlabelled description of a system that no longer matches it, and the person who opens it a year later has no way to tell that it was a plan rather than a report.