Agent pull requests lose the narrative

An agent writes a whole change in one pass, so the pull request arrives with every area touched at once and no order to read it in. Salesforce's engineering team, writing about the surge in AI-generated code, describes exactly this: agent pull requests span backend, config, tests and UI without preserving narrative structure. LinearB's 2026 benchmarks add the size. AI-assisted pull requests run 408 changed lines at the 75th percentile against 157 for unassisted work. The code is usually fine. What is missing is a first file.

What narrative means in a pull request

A human writing a non-trivial change leaves a trail whether they mean to or not. The first commit adds the new table. The second wires the endpoint. The third deletes the thing the endpoint replaces. The tests come last. Even when it is all squashed, the description says "adds X, then moves Y onto it," because the author lived through that order and it is the only order they can describe it in.

That trail is what a reviewer follows. You start where the author started, and each file makes sense because of the one before it. The review is a re-enactment of the writing.

Take the trail away and the diff reverts to what it has always physically been: an alphabetical list of files with line edits under each one. .github/workflows/deploy.yml comes before src/api/routes.ts because of the letter g. Nothing in the ordering is about the change.

Why an agent's pull request has no trail

An agent does not experience the change as a sequence of decisions the way a person does. It plans, it edits across the tree, it runs the tests, it fixes what broke, and it opens the pull request. The intermediate states are real but they are not the story either, because half of them are corrections rather than steps.

So you get a change that is internally coherent and externally shapeless. It compiles. The tests pass. Twelve files moved, four of them config, two of them generated, and there is nothing in the artefact that says which of the twelve you should read first.

The GitHub engineering blog reports that more than one in five code reviews on GitHub now involve an agent, and points at a January 2026 study, "More Code, Less Reuse," which found that agent-written changes carry more redundancy and technical debt per change while reviewers feel better about approving them. That combination is what a missing narrative does to a reader. Without an order to follow, you skim, and skimming feels like reading.

The reader pays for the order the author never wrote down

Reconstructing the order is the expensive part of reviewing an agent's work. You open the file list, guess which file is the centre of the change, open it, discover it calls something you have not seen, go find that, lose your place, come back. Every one of those jumps is a page fault in your working memory. I wrote about the mechanics of that cost in cognitive load in code review; the short version is that the jumps, and not the reasoning, are what exhausts you.

Most teams' first response is to demand smaller pull requests. It mostly fails, because an agent asked to split a change will split it along file boundaries or feature areas, and you end up with four pull requests where three of them are meaningless on their own. You have traded one hard read for four confusing ones.

Why the commit history does not rescue you

The obvious objection is that the commits are right there. Open the Commits tab and read them in order.

Try it on an agent's pull request. The commits you get are usually "implement feature", "fix tests", "fix lint", "address review", or a single squashed commit with the whole change in it. Some agents commit once per tool call, which gives you forty commits that each move three lines. None of that is the order the change makes sense in, because the agent was not narrating as it went. It was converging.

Even on human pull requests the commit history is unreliable for this, which is why reviewers stopped trusting it years ago and started reading the unified diff instead. What agents did was remove the last authors who occasionally wrote a good commit sequence on purpose.

A diagram gives back the shape

The first thing that helps is seeing the whole change as one picture, with the parts of the system it did not touch still on the page. That is what the render at the top of this post is: React's Hooks pull request, 36 changed files and 5,868 added lines, drawn as seven components across four lanes. The public Hooks API sits in the React package. It reaches a dispatcher in the reconciler and a second dispatcher in the server renderer. Feature flags sit in shared config, gating both.

Four sentences, and you now know what the pull request does. The arrangement carried all of it.

A shape answers "what is this change." It does not answer "in what order did it happen," which is the other half of the missing narrative.

A walkthrough gives back the order

That is what walkthroughs are for. On the canvas every PR Lens comment links to, you press play, or W, and the diagram tours the change one step at a time. Each step dims everything else, lights the components and routes involved in that step, and says in one line what happened there.

Step one: signup now publishes an event instead of sending the email inline. Step two: a new worker drains the queue and sends it. That is the order the change happened in, restored by the author or the model that read it, and handed to the reader as a thing they can watch rather than reconstruct.

The order is authored, which matters. It is not the diff's order and it is not the commit order. It is somebody's account of what happened, checked against the diagram: a push carrying a walkthrough is refused unless every step resolves against the components the document actually drew, so a step cannot point at something that is not on the page. What a good pull request walkthrough looks like goes into what makes the steps worth watching.

What to ask for instead of a smaller pull request

Ask for the order. If you run the PR Lens agent skill inside Claude Code, Cursor or OpenCode, the agent that just wrote the change is the one that describes it, and describing what it did in five steps costs it almost nothing because it still has the whole change in context. If you run the GitHub App, the analysis does the same reading from the outside and posts one comment on the pull request, redrawn on every push.

Either way, the artefact you review stops being an alphabetical file list and becomes a picture with a path through it. The code in the pull request is unchanged by any of this. What changes is how long it takes before you know what you are looking at.

For the full method, including where the diagram fits against tests and security boundaries, start with the pillar: reviewing AI-generated pull requests. If what you need right now is a time-boxed routine for the 400-line one already sitting in your queue, how to review a 400-line pull request in ten minutes is the practical version.