How to review a diff written by an agent

The bottleneck in agent-driven development is not writing code anymore. It is reading it. An agent can produce a three-hundred-line diff in a few minutes; a careful review of that diff still takes a person a good while.

That is why Dispatcher puts review in the middle of the loop instead of at the end. Nothing an agent writes leaves its worktree until someone has read the diff and approved it. Here is what we look for when we do.

Start with the shape, not the lines

Before reading any code, look at the file list and the line counts.

• Files you did not expect. A task about the settings page should not touch the auth middleware. Unexpected files are the single most reliable signal that something went sideways.
• Deletions that are larger than additions in a task that should only add behavior.
• Lockfile or config churn that the task did not ask for.

If the shape is wrong, send it back before reading a single line. It is cheaper than reviewing work you will throw away.

The agent-specific failure modes

Human reviewers are trained on human mistakes. Agents make a different set:

1. Weakened tests. The fastest way to make a failing test pass is to change the assertion. Read every test diff as carefully as the code it covers.
2. Invented APIs. A plausible-looking method that does not exist in the library version you actually use. Type checks catch most of these; dynamic languages do not.
3. Silent behavior changes. A refactor that also "fixes" an edge case nobody asked about. Correct or not, it should be its own change.
4. Over-broad error handling. A try/catch that makes the symptom go away and hides the cause.
5. Leftovers. Debug logging, commented-out code, and TODOs the agent meant to come back to.

Read the diff next to the terminal

The diff tells you what changed. The terminal tells you why. When a change looks odd, scroll the agent's session: you will usually find the failed command or the misread error that led to it. That context is why Dispatcher keeps the diff and the terminal that produced it in the same window.

Run it, do not just read it

Run the tests yourself in the worktree, and run the app if the change is visible. Configured run scripts make this one click per task, so it does not depend on remembering the right command for each project.

Sending work back

When something is wrong, be specific about what and where, and let the same agent fix it in the same worktree. "The change to routes.ts renames a public path; keep the old path and add the new one as an alias" gets a better second attempt than "this breaks routing."

Approving is a decision, not a formality. The agent did the typing. You are still the one shipping it.