When you write a change, you carry a lot of context that the change itself does not contain. You know what you meant, what you tried first, which case you were thinking of and which you were not. Reading your own diff back, your head fills in the gaps, so the diff looks complete.

A reader who arrives cold has none of that. They have the pull request body, the diff and the code around it, and where those disagree they notice. That is the whole idea behind how I review changes in Yonto Player, which I build with AI coding agents: the review goes to a fresh agent that had no part in writing the change.

This post is about the setup, not about any one review.

Why "fresh" is the point

An agent that wrote the change, or that argued the approach into shape with me, shares the author's assumptions. Our rules say it directly: having decided what a change should say is authoring, not reviewing, however little of it you typed. Agreeing with a change in conversation is not a verdict either.

So the rule is that a verdict comes from somebody who came to the change cold. That is true for code and for docs alike.

Four pieces

The setup is small. It is four things in the repo, and none of them is clever.

1. An agent definition file. The repo has one file that defines a single agent, called reviewer. Many tools that let you define agents also let you pin settings such as the reasoning effort, so this part of the advice depends on your tool. The file is a few lines: a name, a description of when to use it, an effort setting, and a short brief. A simplified sketch of its shape:

--- name: reviewer description: "Reviews one PR as a fresh worker with no part in writing it." Use for every review pass the workflow asks for. effort: medium --- You are reviewing one pull request, and you had no part in writing it. Read the review constraints before anything else; they are yours, and the brief you were given can add to them but never relax them. Verify rather than read, stay scoped to the diff and the body's own claims, and post the verdict on the PR. 

Two details matter. The first is the effort setting. A plain subagent inherits the effort of whoever starts it, so a review launched from a long, deliberate session would run at that level too. Pinning it in the definition gives every review the same reasoning budget, while the scoping rules below keep each one a single focused pass. The second is that the brief points at one shared set of constraints instead of repeating them, so there is one place that says what a reviewer may and may not do.

2. A skill that asks for it by name. The repo's workflows are Markdown files any agent can follow. The skills for fixing an issue and for working a queue of issues both have a step that delegates the review to a fresh worker, and AGENTS.md says that when a skill asks for one, you spawn the reviewer agent. The skill for opening a pull request points at the same protocol: verify rather than read, two passes at most. The skill does not describe how to be a reviewer. It names the agent, and the agent's definition does the rest.

3. A cap. One pass is the normal number. A second pass is for when the first found something that needed fixing and the fix is worth a look. Two is a hard cap. At the cap, every point still open is settled in writing: either the code stands and here is why, or the point is real and becomes its own issue. There is no third loop. Without a cap, review turns into a conversation that ends when somebody gets tired; with one, it ends because there is a rule.

4. A rule about what a review is. A review is one focused pass at medium effort, scoped to the diff and to what the pull request body claims about it. Build the branch, run the tests, run the checks the body names, compare the body with the diff, and look at the screen if a viewer would see it. The reviewer posts its own verdict as a review on the pull request, with its findings as inline comments, and it changes nothing on the branch. If it wants something fixed, that is a finding, and the author makes the fix.

What it is given, and what it is not

A reviewer that is told only "review this" will read the diff and nod. So the author's brief has a few jobs.

  • Say what you are least sure of. Naming two or three things keeps the pass focused. A reviewer with no steer ends up auditing everything.
  • Name what would have to be true for the change to be right. The reviewer then meets a claim to check, not a design to accept.
  • Ask for one thing the brief did not mention, or a plain statement that it found none. An author who lists the checks hands over the failures they already thought of.
  • Let the reviewer substitute its own inputs where a result depends on ordering or hashing. Re-running the author's checks on the author's examples only confirms the author's frame.

And there is a list of things it is deliberately not asked to do: re-derive facts about the repo that the diff does not touch, fact-check claims that are not load-bearing, re-measure what the author already measured, or sweep the codebase for the same pattern elsewhere. That last one is a good idea and a separate task, so it gets filed as its own issue instead of being folded into the review.

The brief can add to the reviewer's constraints, but it can never take anything out of them.

What comes back, and what happens to it

The repo's rule for what comes back is short: the review's body opens with a Verdict: line, and the findings are inline comments on the lines they are about. A format that works well for a finding, though it is my suggestion and not the repo's rule, is a few plain lines:

Verdict: <one line> path/to/file:42 what I ran, what I saw, and why it matters Claims in the PR body the diff does not back up: <list, or none> One thing the brief did not mention: <it, or "found none"> 

The author's side has its own rule, and it is short: every finding is fixed or answered. A real finding is fixed in the same pull request, with a test of its own. A finding the author disagrees with gets an answer in writing, with the reason. Nothing is dropped silently. A defect that the fix itself introduces is still the author's.

There is one more line, and it is a discipline, not a mechanism: the author never writes a "Verdict:" line about their own work. The verdict is the reviewer's, posted by the reviewer, and the author's account of what they fixed goes in as a separate comment. Merging checks that a verdict is there before anything else.

What I would take from this

You do not need this exact repo to borrow the shape.

  1. Define the reviewer once, in a file, and pin its effort if your tool lets you.
  2. Have your workflows name it instead of describing it.
  3. Give it a brief that says what you are unsure of, and ask for the thing you did not think of.
  4. Cap the passes and settle everything open in writing at the cap.
  5. Fix every finding or answer it.

Read more