CutplaneJoin the private beta

Writing

Your agent changed 60 files. Where do you start?

The diff is the wrong entry point when an agent wrote it. Start with the components that changed, then the ones they reach. Here is the order, and why.


You gave an agent a feature. It came back with sixty files. The GitHub page says +1,847 −312, the file tree is three screens tall, and you have the specific feeling of being asked to audit something you did not watch happen.

The instinct is to start at the top of the file list. Don't. The file list is sorted alphabetically, which means it is sorted by nothing.

Here is the order that actually works.

First: collapse sixty files into components

Sixty files is not sixty decisions. It is usually two or three decisions plus their mechanical consequences.

Group the changed files by the part of the system they belong to — auth, billing, the API layer, whatever your codebase's real divisions are. You will nearly always find the sixty files land in four or five groups, and that two of those groups contain one file each and are noise.

Now sort the groups by how much of them changed. The group where thirty files changed is the change. The group where one file changed is a call site that got dragged along.

This is the single highest-leverage minute of the review, because it converts an unordered list into a ranked one, and everything after this reads the ranked one.

Second: separate the new from the modified

Within the dominant group, split the files two ways:

  • New files are decisions. Something did not exist and now does. Every one of them introduced a name, a responsibility, and a place in the dependency graph.
  • Modified files are consequences. Something already existed and now behaves differently.

Read the new files first. They are fewer, they are where the agent's judgement shows, and they are the ones that are cheap to change now and expensive later. A badly named, badly placed new file becomes load-bearing in about two weeks.

Third: for each new file, ask where it sits

Not "is this correct". Ask:

  • Which component does it belong to?
  • What is the new responsibility?
  • Who uses it?
  • What does it use?

If the answer to "who uses it" is nothing, the agent wrote a file it did not wire up — which happens more than you would expect and is invisible in a diff because dead code looks exactly like live code.

If the answer to "what does it use" crosses a boundary your codebase respects, that is the review comment, and it is worth making before the PR merges rather than in a refactor next quarter.

Fourth: walk outward from the modified files

For the modified files, the question is what else is affected. Take each changed public function and ask who calls it, then who calls them.

One hop is almost always worth walking. Two hops is worth walking when the first hop crossed into another component. Beyond two hops you are usually discovering that your codebase is tightly coupled, which is true but is not this PR's fault.

The output you want is a sentence like: "the session change reaches Checkout and subscription renewal". That sentence tells you what to test. Nothing in the diff tells you that, because the affected code did not change. What you are describing when you say it is the change's blast radius.

Fifth: the three things that hide in a big file list

In sixty files these are trivially easy to miss and each one outweighs the rest:

  • A migration. It is one file among sixty and it is the only one you cannot undo by reverting.
  • A new route. New public surface. Check its auth.
  • A new dependency in package.json. One line, permanent, and it is now in your supply chain.

Search for these explicitly before you finish. Do not rely on noticing them.

When to stop

Stop when you can say what the change did in two or three sentences without looking. Not when the file list is exhausted.

For a sixty-file agent change, that point usually arrives around file eight. The remaining fifty-two are the mechanical spread — the import updates, the call-site renames, the test fixtures — and reading them individually is how a review takes four hours and finds nothing that the first eight did not already show.

The uncomfortable part

If you cannot get to "I can describe this change" after a serious attempt, the correct answer is not to read harder. It is that the PR does more than one thing and should be split.

That is an awkward thing to say about a change an agent produced in ninety seconds, because splitting it means another round trip and the whole appeal was speed. It is still right. A change you cannot describe is a change you cannot review, and merging it means the next person to touch that code is doing archaeology on something nobody ever understood.


This ordering is mechanical enough to automate, which is what Cutplane does: it groups the files into components, ranks them, separates arrivals from modifications, and walks the impact outward — then links every claim to the line of code it came from. There is a real report on a public pull request if you want to see the output before the input.


All writing