The second job of review, and how it broke

Review was never only about defects

Ask why teams review code and you get the defect answer. That was always the smaller half. The larger half was that review is how understanding of a system spreads through the people who maintain it.

Specifically, four things happened in a review that had nothing to do with finding bugs:

• A second person acquired a working model of a part of the system they did not write.
• Conventions propagated, because someone said “we usually do this the other way” and a reason came with it.
• Newer people learned by watching what senior people noticed.
• The bus factor went up by one for that area of the code.

Every one of those depended on both people having thought hard about the change. The author thought hard because writing it required it. The reviewer thought hard because reading unfamiliar code requires it.

What broke

The author’s half is no longer guaranteed.

A change can now be produced, run, tested and submitted by someone who has read it once, quickly, and understood the shape rather than the substance. That is not negligence; it is what the tools are for, and for a great deal of work it is correct. But it means the review conversation can happen between one person who has not deeply understood the change and another who is reading it for the first time, in forty minutes, under time pressure.

When that happens, the defect-finding half of review degrades. The knowledge-transfer half disappears entirely, because there was no knowledge to transfer. And the loss is silent: nothing fails, nothing goes red, and the effect appears eighteen months later as a service that four people are nominally responsible for and none of them can explain.

Four practices that put it back

The walkthrough, not the approval. For any change to a system’s core, fifteen minutes on a call: the author walks through the diff and says why each significant decision is there. Not a test, a routine. Everyone does it, including the most senior person on the team, which is what stops it feeling like an accusation.

What this buys, concretely: the author has to construct the explanation, which is the act that produces understanding. Somebody explaining a change out loud will find their own gaps in the first three minutes, reliably, whatever produced the code.

Reverse review. A junior reviews a senior’s change, and a senior reads that review afterwards and responds to it. Twenty minutes of a senior’s week. It is the fastest judgement-building exercise available and it has almost no adoption, because the default assumption is that review flows downhill.

Rotate the reviewer, not just the author. If the same person always reviews the payments code, that person is the only one who understands the payments code, and review has become a bottleneck disguised as expertise. Assign a second reviewer whose job is explicitly to learn rather than to approve.

Write the why in the pull request, not in the code. A description that says what changed is redundant with the diff. A description that says what else was considered and rejected is the only place that information will ever exist. Three sentences:

Considered adding the currency to the line item and computing at read time. Rejected: historical invoices would silently change when rates move. Storing the converted amount at write time costs us a backfill and gives us immutable invoices, which is what finance actually asked for.

That paragraph is worth more than the diff in two years, and it is the thing that no tool will write for you, because it is a record of a decision rather than a description of code.

What this costs

All four practices consume the constrained resource. Fifteen minutes of walkthrough, twenty minutes of reverse review, a slower second reviewer: that is real capacity taken from the stage that was already the bottleneck.

The defence is that you are choosing which bill to pay. Knowledge that does not transfer is not free; it is deferred to the incident, the handover, the resignation, and the rewrite that gets proposed because nobody can safely modify the thing that exists. Those bills are larger and arrive at worse moments.

The practical compromise most teams land on: apply all of this to the parts of the system where being unable to explain the code would be expensive, and let the rest go through with an ordinary review. Deciding which parts those are is a five-minute conversation and most teams have never had it.