An agent opened a pull request on our service last week. Six hundred lines. It rewrote how we handle webhook retries and deduplication, an area that is fiddly and easy to get subtly wrong. The diff was clean. The tests were green. The commit messages were better than mine usually are.
And I felt the specific dread that I think a lot of engineers are starting to feel in 2026. I was the reviewer. I had not written any of this. I had no idea why it was shaped the way it was. To review it properly, the way I would want my own code reviewed, I was looking at the better part of an hour of carefully reconstructing intent from the code itself. I did not have that hour. So I did what almost everyone does in that situation, which is skim it, decide it looked reasonable, and approve.
That moment is the actual problem with AI-written code, and it is not the one people argue about.
The bottleneck moved, and most teams have not adjusted
The tired debate is whether agents write good code. In 2026 that argument is mostly over. They do. They plan, they read the codebase, they run the tests, they back out of dead ends, they open pull requests that clear most review bars. If you are still litigating whether the code is any good, you have not used a current agent in a while.
But here is what follows from that, and it is the part teams have not absorbed: if writing the code is no longer the slow step, then reviewing it is. And review does not scale the way generation does. An agent can produce five well-tested pull requests before lunch. Your senior engineers cannot deeply review five pull requests before lunch, not on top of their own work. The volume went up and the review capacity did not, and something has to give.
What gives is the depth of review. It degrades, quietly, into a skim. People approve fluent diffs they have not truly read, because reading them properly costs more time than anyone has. The green check still appears. It just means less than it used to. That is a governance failure wearing the costume of a passing review, and it is happening on a lot of teams right now without anyone deciding it should.
Why agent PRs are harder to review than human ones
It is worth being precise about why this is worse than the human version of the same problem.
When a teammate sends you a pull request, you usually share context with them. You were in the standup. You saw the thread. You know roughly why they are doing this and what constraints they are under. You review the diff against intent you already hold in your head.
With an agent PR, that shared context is gone. You are handed a substantial, confident, well-structured diff and no narrative of why it is shaped the way it is. You cannot ask the agent in the hallway. So reviewing it well means reconstructing intent purely from the code, which is slow, error-prone, and exactly the work that gets skipped under time pressure. The fluency makes it worse, not better, because fluent code invites you to assume the thinking behind it was equally sound.
The mistakes that survive this are not syntax. They are contextual. The agent leaned on an assumption that is true in general and false for your system. In our case, the dedup rewrite quietly assumed webhooks could be deduplicated on payload, when our whole reason for keying on a separate idempotency field was that one upstream sends byte-identical payloads for genuinely distinct events. Perfectly reasonable code. Wrong for us, for a reason that lives in our history and nowhere in the diff.
You cannot fix this by reviewing harder
The instinctive responses do not hold up.
"Review everything as carefully as before" does not survive contact with rising volume. The math does not work. "Trust the agent" is not a governance posture, it is the absence of one. "Add more CI rules" helps with the syntactic class of problem that is already mostly solved, and does little for architectural mistakes, because a contextual violation is not a lint rule, it is a conflict with a decision your team made that no checker knows about.
The thing that actually changes the equation is not reviewing harder. It is changing what review consumes.
Read the reasoning first, the diff second
Here is the shift. Instead of handing a reviewer a raw diff and asking them to reverse-engineer the intent, hand them the story of how the work came to be, first. The decisions it relied on. The constraints it was operating under. The context it was given before it started. The questions it hit and who answered them. The approaches it tried and reverted. The points where a human stepped in and steered it.
Then the reviewer reads that narrative, and reads the diff second, with intent already established. A contextual mistake that is invisible when you are staring at code becomes obvious the moment you can see the reasoning behind it. If I had seen, up front, that the agent's plan rested on deduplicating by payload, I would have caught it in five seconds, because I know why that is wrong here. Buried in six hundred lines, I missed it entirely.
This is what I am building as Branch Story. For any branch or pull request, it reconstructs that narrative, grounded in your team's actual captured decisions rather than guessed from the diff. It reads as a story of how the work happened, not a log dump, because a log dump is just more material to skim and the entire point is to stop skimming.
It works for human-written branches too, which matters more than it sounds. A teammate reviewing a teammate gets the same narrative, so review becomes consistent across human and agent work instead of being two different activities. And honestly, that consistency is part of what makes a team willing to let an agent open pull requests at all. The blocker on agent autonomy was never whether the agent could write the code. It is whether a human can responsibly sign off on it. Trust is the unlock, and trust comes from being able to see the why quickly.
What it does not do
I want to be straight about the limits, because overselling this would be its own kind of damage. Branch Story does not replace your judgment and it does not certify that code is correct. It makes the why legible so your judgment is fast and accurate instead of slow and guessed. And it is only as good as the context behind it, if your team's decisions are not captured anywhere, there is no story to reconstruct, which is exactly why the capture side is the hard part and where most of my work goes.
But the direction feels right to me. As more of the code gets written by something that cannot explain itself in the hallway, the scarce resource is not code and it is not review hours. It is legible intent. That is the thing worth building.
When you review an agent's pull request, are you reading it, or are you approving it? Be honest. That gap is the whole problem.
Top comments (12)
Hey, this article appears to have been generated with the assistance of ChatGPT or possibly some other AI tool.
We allow our community members to use AI assistance when writing articles as long as they abide by our guidelines. Please review the guidelines and edit your post to add a disclaimer.
Failure to follow these guidelines could result in DEV admin lowering the score of your post, making it less visible to the rest of the community. Or, if upon review we find this post to be particularly harmful, we may decide to unpublish it completely.
We hope you understand and take care to follow our guidelines going forward!
Honestly, I think Git needs to upgrade. Include the agent session with the PR, so you can read through the reasoning. Ideally, you would be able to pull it into your own model and continue conversation with it. That way you can ask questions that your model can explain. Imo, that's the future of code reviewing, because syntax is perfect, tests are all green, but to understand why, that needs adjusting in order to accommodate agents.
Yeah, this is where I think it goes. The session is the missing artifact. Right now the reasoning gets thrown away the moment the PR opens, and everyone downstream is reconstructing it by hand. Attaching it to the branch so a reviewer can actually interrogate it, ask their own model why a given choice was made, is what review looks like once the agent is the one writing.
The one thing I'd add from building this: the raw session is too noisy to just bolt on. Half of it is dead ends and tool output nobody needs. The signal is the decisions and the moments a human stepped in and steered, lifted out of the transcript. Pulling that out is most of the work, and it's why I'm shaping it as a story instead of a dump.
That's the part I'm building as Branch Story (which is live), it lives in a VS Code extension if you ever want to see the shape of it. But you've got the direction exactly right.
True, I mean if it's a week long dev cycle, it's millions and millions of tokens, far too much for the LLM to actively cache. Maybe worth using a codebase map then draw association to each file per-prompt, so when you query it, it can swap in just that chunk as context. Similar to what I built for V.E.L.O.C.I.T.Y. OS. I'll give it a look at some point, it wont really be all that usable to me, because the foundry runs swarms of instances at once, each with individual scoped tasks, etc and the ledger stores every decision already, so it's pretty good for understanding what, why, when, where, how, but for anyone using a single agent, or an ide in general, that seems extremely useful.
Yeah, you've got the architecture right. You don't cache the transcript, that's a losing game. The session gets keyed against a map of the codebase, decisions associated to the files and topics they touch, and you pull in just the relevant slice per query. That's basically how it works under the hood, so we're thinking the same way there.
And you're right that a decision ledger already gets you most of the what, why, when. That's the capture side, and it's the hard part, sounds like you've solved it well for velocity. The bit I'd pull apart is that a ledger is built for querying, and a human reviewer doesn't want to query, they want to read. Turning the ledger into something a person can go through top to bottom and come away holding the intent is the layer I'm actually building. Different job from storing it.
On the swarm point, that's actually the exact case I built the handoff piece for. When multiple agents work a branch, each one passes its knowledge forward so the next doesn't start from zero, and the story stitches across them instead of leaving the why scattered per instance. So it might sit closer to your foundry than you'd expect. Either way, appreciate you giving it a look whenever you get to it.
The missions and mission reports are pretty good at reviewing what the model did and why it was done in a way, but if you want a summary from A-Z, that's the final audit's job, as it produces 2 files, the full report, which is highly detailed and the summary, which covers all parts, but as an overview. Interesting that they're so similar, do you work dir-file or file-dir for your propagation?
Yeah, that two-file split maps almost exactly onto how I think about altitude. Your full report and your summary are the same instinct I'm working from, I just fold them into one surface instead of two files. The story reads at the summary altitude, and you expand any beat into the evidence sitting behind it. Progressive disclosure rather than two artifacts, but same idea: one level to read, one level to verify when a claim doesn't sit right.
On propagation I work file-dir, so bottom-up. The decision is the atomic unit and it anchors to the files it actually touched, then the directory, topic and branch views are rollups over those file-level decisions. The reason is that a reviewer is staring at a diff, which is inherently file-level, so anchoring the why at the file keeps the story lined up with exactly what they're looking at, and the higher-level narrative composes upward from there. Directory-first read cleaner on paper but it kept drifting off the actual change.
Curious which way you landed, since your missions sound scoped more like units of work than files, so I'd guess you lean dir-file. What pushed you there?
Same setup, except starts off with triggering a function that maps the codebase, then a file-up audit to determine each file's purpose, dependencies, etc. then the architect model writes an overarching plan, which is split down dir by dir, to file, then the file level executes their missions, hand up to their parent that audits, refines, etc. till it's back at architect level, where a back and forth audit is done between 2 models, till they come to consensus that the codebase is perfect. Though worth noting that the summary and the detailed files, are interpreted by the interface, which lets you expand to view the file edits and the detailed view, along with a quick-view for all the relevant files, eg. the model mission file, the model's log, the code-snippets and a relationship diagram (mermaid) that shows the dependencies across the codebase from the edited section. That way reviewing is more drilling down, than reading separate files, opening editor, etc. It's also what gets passed to the agents when the user wants to refine the app, that way it has a small context initially, but can query with a LoD parameter to get the depth from the relevant sections.
The part that would stop me cold is "it rewrote webhook retries and dedup, tests were green." Green on the existing suite is the weakest possible signal there, because the agent wrote the code AND stayed inside the assumptions your current tests already encode. For a change like that I gave up reviewing the diff as prose and started reviewing the test delta: does this introduce a failure mode the suite does not cover, and is there a case that would go red if the dedup key were subtly wrong. If the answer is no, the PR is not reviewable yet no matter how clean it reads, and the ask back to the agent is "add the test that fails without this change," not "explain the diff." That moves the hour from reconstructing intent to checking coverage, which is the part that actually scales when generation gets cheap.
The gap it leaves is that you still have to know what the failing case should be. In our dedup example the test that goes red is "two byte-identical payloads with different idempotency keys must not collapse," and nobody writes that test unless they already know the payloads can be identical. That knowledge is the same contextual thing that wasn't in the diff. So I'd run them together: the narrative tells you which invariant actually matters here, then you demand the test that proves the agent respected it. Coverage-checking scales, but only once you know what to cover.
The 600-line PR nobody wants to review is where the whole model breaks down. Review was the safety net, and it assumed a human volume of change. Agents blew past that, and LGTM on 600 lines nobody read is just trust with extra steps. The fix isn't heroic review, it's shrinking what has to be reviewed by hand: enforce the boilerplate and the standards mechanically so human attention goes to the handful of decisions that actually carry risk. A 600-line diff isn't the problem; 600 lines where every line is equally unverified is.
the bottleneck-moved framing is right, and the part i'd underline is buried in your own example. the dedup-by-payload mistake is the kind a narrative makes worse before it makes better, because the agent would have narrated that decision as sensible. "i deduplicated on payload for simplicity" reads fine. the story of the reasoning is still the agent's account of itself, and a confident wrong assumption produces a confident wrong narrative.
which is why the line at the end is the load-bearing one: grounded in the team's actual captured decisions, not reconstructed from the diff. that's the difference between a narrative you can check and one you just read. the first catches "you deduped on payload but our idempotency key exists for a reason." the second just makes the wrong call easier to approve because now it has a story attached.
so i think the real scarce thing isn't the narrative, it's the captured decision the narrative can be checked against. which tracks with you saying the capture side is where most of your work goes. that's the hard half and the right half.