Reviewing agent-made changes by their reasons
By Soumen Sarkar · October 2026
Playbook. Review agent-written changes by reading their reasons first: check the calls, settle the assumptions, and fix forward instead of gating.
How do you review agent-made changes by their reasons?
Read the change's reasons before its diff: what it's for, the calls it made, what it assumed, and what was tried and dropped. Spend your attention on the calls and the assumptions, read the code where the reasons point, and when something is off, correct the course with a small follow-up rather than holding the whole change at the gate. High-stakes calls still get the closest look, and they get it first.
That's the third VibeFlock principle: we don't guard the gate, we correct the course. When agents land dozens of changes a day, a reviewer who reads every line of every diff becomes the wait everyone else is stuck behind. Reasons let a reviewer see in a minute what matters in a change, and spend the rest of their time where a mistake would cost the most.
Who is this for, and what do you get?
It's for reviewers and tech leads facing more agent-written pull requests than they can read line by line, and for anyone who has opened a large agent diff and wondered where to start. It works in any git host and with any agent, as long as each change carries its reasons in its description.
What you get:
- Reviews that start with the why, so the diff makes sense on first read.
- Attention on the decisions and assumptions, where mistakes are expensive, not on formatting.
- Wrong assumptions caught while they're small, with the agent told exactly what to change.
- Lessons from review recorded once, so the next agent doesn't need the same correction.
What do good reasons look like?
Short, specific and honest about what isn't known. The change reasons template has the shape. Here's one for a hypothetical change in Exports · lib/exports:
For: let workspace admins export the member list as CSV.
Calls made:
- Rows are streamed, not built in memory, because large
workspaces have tens of thousands of members.
- The export reuses listMembers(), because it already
applies the workspace's visibility rules.
Assumed (not confirmed):
- Email addresses are included for admins only. High stakes: access.
Tried and dropped:
- A background job that emails the file, because most
exports are small and finish in seconds.
Look closely at: the admin check in exportMembers().
A reviewer reading that knows in under a minute where to look: the admin check, and the one assumption about access. The streaming and the reuse of listMembers() are calls with reasons that hold; they don't need a second opinion.
The steps
- Require reasons on every change. Every pull request description carries them, under the same headings, whether a person or an agent wrote it. Agents write them at the moment of the change, when they know.
- Read the reasons first. Before opening the diff, read what it's for and the calls made. If the purpose is wrong, nothing in the code matters yet.
- Check the calls against what the team decided. Does any call contradict a decision that stands in that area? If so, one of them has to go. Decide which, and record it.
- Settle the assumptions. Confirm or correct each one, high stakes first. A correction is a sentence: "No, members can see each other's emails on the paid plan."
- Read the code where the reasons point. Start at "look closely at", then the code behind each high-stakes assumption. Skim the rest for anything the reasons don't explain.
- Land it, and fix forward. If the change is sound and the corrections are small, land it and make the fix a follow-up with its own reason. Hold a change back only when landing it would do real harm: lost data, wrong charges, access that shouldn't exist.
- Record what review taught. If you made a correction the next agent would also need, write it as a decision or a rule in the area, so it's followed, not repeated.
How do you split your attention across a day of changes?
When a team lands dozens of agent-made changes a day, the question isn't how to read each one fully. It's where reading fully pays off. The reasons let you sort before you read.
- Read every change's reasons. It takes a minute each, and it's how you find the ones that matter.
- Read high-stakes changes line by line. Anything whose reasons mention data, money, access, public interfaces or deleting things gets the full review, first, before the rest.
- Read the pointed-at code for everything else. "Look closely at" and the code behind each assumption. If the reasons are clear and the calls hold, that's enough to land it.
- Send back changes without reasons. A change that can't say what it's for isn't ready for review. Ask the agent to write them; it usually takes one turn.
This isn't a lower bar. It's the same bar, applied where it does the most good, by a reviewer who isn't buried.
What does a correction look like?
A correction is a sentence, aimed at a specific call or assumption, with a reason. In the export example, the reviewer might write: "Members on the paid plan can see each other's emails, so include emails for everyone on paid workspaces, admins only on free ones." That's all the agent needs.
The change can land as it is, because admins-only is the safer of the two answers. The follow-up opens straight away, as its own small change, with its own reasons: "For: include member emails in exports for paid workspaces. Calls made: reuse the plan check from billing, because it's the one the rest of the product uses." And because the next export someone builds will need the same rule, the reviewer records it as a decision in the area.
That's fixing forward: the course is corrected within the hour, the work never stopped, and the lesson is written down where the next agent will find it.
What should you tell your agents?
## Every change explains itself
In every pull request description, under "Why this change", write:
For: what the change is for, in one sentence.
Calls made: each decision, with its reason.
Assumed (not confirmed): each assumption, marked high stakes
if it touches data, money, access, public interfaces or deleting.
Tried and dropped: approaches you abandoned, and why.
Look closely at: the part a reviewer should check first.
Write reasons, not a summary of the diff.
When a reviewer corrects you, make the change, say what you changed,
and record the correction as a decision if it will matter again.What should you watch for?
- Reasons that restate the diff. "Added exportMembers()" is a description, not a reason. Push back until the reasons say why.
- Assumptions left out. An agent that lists no assumptions on a change touching permissions probably made some. Ask for them.
- Reading reasons instead of code on high-stakes changes. Reasons tell you where to look; they are no substitute for looking. Anything touching data, money or access still gets read line by line.
- Fix forward as an excuse. Landing with a known follow-up only works if the follow-up happens. Track it as work in progress with an owner, not a comment.
- The same correction twice. If you correct the same thing in two reviews, it isn't in the record yet. Write the decision.
- Rubber-stamping. Reasons make review faster, not optional. If reviews get quick and corrections stop, check that someone is still reading.
How do you know it's working?
- Review comments change shape. Fewer "why did you do this?" and more "this call is wrong, because…" comments.
- Corrections are small. A wrong assumption becomes a one-function follow-up, because the agent named what depended on it.
- Changes wait less for review. Pull requests don't sit for a reviewer with time to read everything, because nobody needs to read everything.
- Corrections stick. The next agent in the same area follows the corrected call without being told.
- Clashes are caught early. Calls that contradict a standing decision show up in review, or before it, rather than in production.
What does Campfyrr automate?
In Claude Code, Campfyrr writes the reasons for the change at the moment it's committed, from the session's own record, so the reviewer gets them without the author doing anything.
- Reasons on commit and pull request. When a session commits or opens a pull request, the hook writes the change's reasons for its reviewer (what it's for, the calls made, what was assumed, and what was tried and dropped) and gives the agent a link to put in the pull request description. Other clients call
change_story for the same thing. - Assumptions already routed. Assumptions the agent stated with
state_assumption have usually reached the person who knows before review starts, and corrections reach the agent at its next turn. - Clashes caught at once. A decision recorded with
log_decision is checked against the ones that stand. If it contradicts one, the newer call stands, the earlier one is marked superseded, and the change shows in the Activity feed. - Landed work in plain words. Activity's feed shows finished work as what happened and why it matters, and its weekly card counts clashes caught and wrong assumptions caught.
Campfyrr doesn't read or store your code or diffs, and it doesn't approve or block anything: review stays in your git host, with your rules. For the shorter version, see how to review a pull request an agent wrote and what happens when an agent's assumption turns out wrong.
A reviewer who starts from the reasons doesn't have to guard every line. They check the calls, settle the assumptions, and keep the course right, change after change.
The principle behind this: Fix forward: We don't guard the gate. We correct the course.
Move as one at agent speed. Nobody waits. Add Campfyrr to Claude: it briefs every agent before it touches the code, keeps assumptions and handoffs where the team can see them, and never takes your code (what it keeps).