← all posts

11/17/2026 · #ai #reviews

More Than the Diff

A merge request shows what changed. It can't show why it changed, or what else depends on the code it touches.

In The Branches That Matter, I wrote that with AI answering the common forks of a project, experience now shows in the review. This post is about what a review needs: the right context going in, and a steady view of what comes out, so that reading a change is a guided tour instead of a pile of findings.

The Diff Is the Smallest Part

Say a merge request moves this site's CV from /cv to /resume. The route, the CV's links and the tests all move together, and the pipeline is green. Every line of the diff is right.

What's wrong is outside it. cv.ericveenendaal.com redirects to /cv through a Cloudflare rule that lives in another repository, the one that manages my domains. Merge the change, and every link to the subdomain ends on a 404.

fig. 1The Diff Can't See the Redirect
The Diff Can't See the Redirect

A reviewer who reads only the diff approves it. A reviewer who knows the site asks where the redirect went. The difference isn't skill at reading code. It's context.

The same goes for an agent. Given only the diff, it can judge names, style and local bugs, which AI already gets right on its own. The forks that matter can only be judged against what's around the change.

Three Questions, Three Kinds of Context

In the last post, the forks that needed me came in three kinds: testing the working prototype, alignment with other systems, and plans for the future. A review asks the same three questions of a change, and each one has its own context.

  • Does it work? The tickets' acceptance criteria, and the pipeline that ran the tests.
  • Does it fit? The application's notes, with its conventions, gotchas and past decisions, and the related applications that read or call what it changes.
  • Where does it go? The todo that asked for the change, with its plan, and the project it belongs to.

None of that is in the diff. The CV change passes the first question and fails the second: it doesn't fit a system it can't see. The third question catches a different kind of mistake. A change that's right today can still close a door the project means to walk through next month.

fig. 2Three Questions, Three Kinds of Context
Three Questions, Three Kinds of Context

Gathering the Context First

In the last post I introduced Mission Control, the project manager on my Mac with Claude Code built in. Its reviews collect that context before the agent reads a line of code.

Review with Claude on a merge request sets up a review of its own:

  • It finds the application whose repository the change is in, and checks out the change's head in a worktree, so the agent reads the real code and not just the diff.
  • It lists what the agent reads first: the description and commits, the tickets the change names with their acceptance criteria, the open threads so it doesn't repeat them, the pipeline, the application's notes, the repository's REVIEW.md, CLAUDE.md and CONTRIBUTING.md, and the todos and projects that link its tickets. I tick what applies before it starts.
  • It adds the related applications, the ones the application's notes name, as more folders for the agent, which checks their code for anything the change breaks.

The review's first message lands in the chat's box, and nothing starts until I send it.

fig. 3What a Review Reads
What a Review Reads

For the CV change, the site's notes name the repository that manages my domains, so its code is part of the review. The redirect turns up where it lives, and the acceptance criterion "every old link still works" comes back as not met.

Findings Need a Fixed Shape

Context going in is half the work. The other half is what comes out.

Ask an agent to review a change in a chat, and the answer is prose: a long reply with its findings in whatever order they came up, nits next to data loss, each one pointing at "the redirect logic" instead of a line. Run it again and the same findings come back in a different shape. Before I can judge a single one, I have to find it, rank it and work out where it lives.

fig. 4The Same Review, Run Three Times
The Same Review, Run Three Times

So Mission Control doesn't take a review as prose. The agent writes each finding with a tool, and every finding has the same fields: the lines it's about, a short title, how much it matters (an issue, a suggestion, a question or a nit), the comment as it would be posted, and the suggested change when the fix is small. It finishes with a summary: a short paragraph, and each acceptance criterion as met, not met or partly, linked to the line that decides it.

Code then checks every finding before I see it:

  • Above the floor. I choose whether nits, suggestions or only issues come through. Anything below the floor goes in the summary instead.
  • Within the count. At most 15 by default. Past that, the agent improves a finding it already has, or sums up the rest.
  • On the change. Its lines must be lines the diff shows, in one hunk, as GitHub and GitLab require. Anything else is refused, with the reason.
fig. 5A Finding Has a Shape
A Finding Has a Shape

The agent decides what it found. Code decides where each finding goes and how it looks. The findings change from review to review, but their shape never does, and that is what makes the view deterministic.

A Guided Tour, Not a Pile

A review asks a lot of working memory: the criteria, the line, the code around it, what the related applications expect, what the pipeline said, what the agent said, and the finding itself. Working memory holds a handful of things at once. Past that, something drops out, and a dropped thing is how the redirect gets missed.

fig. 6What a Review Asks Me to Hold
What a Review Asks Me to Hold

So a review in Mission Control is a tour, and it's the same tour every time. It opens with the summary. Next come the acceptance criteria, each with its verdict and a link to the line that decides it. Then the change, file by file, each finding under the lines it's about. Next to decide takes me to the next open finding, in the order they sit in the change.

Every stop is one decision, with its context beside it: add the finding to my review, edit its words or its fix, or discard it. When I want to know more, I ask in the chat docked beside the diff. A file and line in the answer is a link that opens the diff there.

fig. 7A Guided Tour of the Change
A Guided Tour of the Change

The Calls Stay Mine

The agent proposes and I decide. It writes only to its own review: it adds a finding, improves one, sums up. Anything that would post, approve or change the code asks me first. Every finding starts as proposed, and only what I add to my review is posted when I submit, as me, with gh or glab.

fig. 8A Finding's Life
A Finding's Life

New commits don't undo that work. Each finding follows its lines to wherever the code moved, and one whose lines changed says so and waits to be checked again. Review again moves to the newest commit and keeps what I decided.

Context In, Decisions Out

Reviews used to mean reading every line. With AI writing more of the lines, and reviewing them too, the review is where the forks get checked: does it work, does it fit, and where does it go next. Those questions are answered against the context, not against the diff.

fig. 9The Review Checks the Forks
The Review Checks the Forks

So a review tool has two jobs. Bring the context in: the todo, the project, the tickets, the notes and the applications next door. Then keep what comes out steady: findings with a fixed shape, in a fixed order, one decision at a time.

The CV change shows why. Every line of its diff was right. Its context said otherwise.