How to Review a Pull Request
A code review checklist for the part a person has to do: intent, one path through the change, and an honest scope when you do not know the code.
Most code review checklists are a list of questions a linter, a type checker, or a test run already answers. Names, formatting, "is there a test somewhere." People open them once, feel virtuous, and go back to skimming the diff from the top.
A review that finds real problems has an order. Read why the change exists before you read how it was done. Then follow one path all the way through, including the branch where it fails. Then say, out loud in the review, what you actually looked at.
Before you open the diff
Three minutes that save the rest of the hour
- 1
Read the description and the linked issue
You are judging the diff against its intent. If you cannot tell what the change is for, ask for a description and stop. That is the review.
- 2
Restate the change in one sentence
If your sentence and the title disagree, the rest of the review is you guessing. Say so in a comment before you start line-reading.
- 3
Look at the size
Past a few hundred lines, defect detection falls off and reviewers skim. Asking for a split is a normal comment, not a rejection. A refactor, a feature, and a dependency bump are three pull requests.
The checklist
Run this in order. Stop when you hit a no. Style that a formatter would fix does not belong on the list.
Pull request review
- ✓ I can say what this change is for, in one sentence, without the diff.
- ✓ The diff matches that sentence. Unrelated edits go in another pull request.
- ✓ I followed one path from the entry point through the failure branch.
- ✓ Anything deleted or renamed has no remaining caller. I searched, I did not assume.
- ✓ A test would fail if the change were wrong. For a bug fix, that test fails on the old code.
- ✓ Input that crosses a trust boundary is checked. Authorisation is checked, not only identity.
- ✓ I marked what blocks the merge, and I marked the rest as a nit.
- ✓ Where I do not know the code, I said so, and I named who should look.
Reviewing a pull request in a codebase you don't know
You do not need to have onboarded. You need to know what this change assumes, and those assumptions are usually visible from the diff and the files next to it. A component it calls exists and behaves the way the call implies. Something it removes has no live caller. Data it writes is read by something, in the shape it wrote. A boundary it crosses was meant to be crossed.
Enough to review without pretending
- 1
Start from the tests
Tests are the cheapest documentation in the repo. They use the vocabulary of the domain and they state the behaviour in a few lines. Read them before the implementation.
- 2
Follow one path
Pick the path the change exists for. Entry point, the check, the write, the failure branch. You are checking that the change holds together, which is a property of the change.
- 3
Search for what was removed
Grep the names. This takes a minute and it is the check reviewers skip when they feel they lack standing to comment.
- 4
Scope the review in the summary
"I reviewed the API changes. Someone who knows the billing job should look at the lock." That is a useful review. A silent approval of code you did not understand is not.
Code review on a small team
A small team does not need a review policy that would suit a platform org. It needs three decisions, made once, so they are not relitigated on every pull request.
Decide these once
- 1
How many approvals
One is enough for most changes. A second pair of eyes is for sign-in, payments, permissions, and migrations. Two approvals on everything halves throughput.
- 2
Who reviews
Rotate by default, so one person does not become the only one who understands a service. Let the author ask for a specific person when the change needs them.
- 3
How fast you respond
A day is a reasonable maximum for a response. A response can be "I will look tomorrow morning." Silence is what makes authors batch more into the next pull request, which makes the review harder still.
Put formatting, lint, and the test run in CI, and let them fail the build. If an AI reviewer takes a first pass, treat it as that: a first pass for the mechanical mistakes. The approval stays with a person, because the person is the one who knows why the system is shaped the way it is.
Why pull requests sit unreviewed
When a change sits for days, the author starts something else. The branch goes stale. The review, when it finally happens, costs a context switch on both sides. The wait is usually one of four things, and only one of them is "people are busy."
- The diff is too big to start. Opening it feels like an afternoon, so it waits for an afternoon that does not come.
- The description does not say why. The reviewer has to reconstruct the task before they can review the code, so they don't.
- One person is the reviewer for everything. Their queue is the team's cycle time.
- Nobody has agreed when a review is late, so late is just the weather.
The fix is dull and it works. Smaller changes. A description that says why in the first two lines. A rotation, so the expert is requested for the expert parts and not for every typo. A response time the team has actually said out loud. Check the queue in standup the way you check blocked tickets. A pull request with no reviewer is blocked.
Put the reason next to the change
Prodigent briefs the pull request before you open the diff, sets the noise aside, and shows the team's knowledge beside the line it affects. You still decide.
Try Prodigent free