{"course":{"slug":"how-software-changed","title":"How Software Development Changed","url":"https://addaly.com/learn/how-software-changed","level":"intermediate","track":"work"},"lesson":{"slug":"review-as-knowledge-transfer","title":"The second job of review, and how it broke","url":"https://addaly.com/learn/how-software-changed/review-as-knowledge-transfer","position":18,"of":87,"minutes":9,"answer":"Review transferred understanding only because both people had thought hard about the change, so when the author has not, the knowledge-transfer half of review disappears silently and reappears as a system nobody can explain.","keyIdea":"Review transferred understanding only because both people had thought hard about the change, so when the author has not, the knowledge-transfer half of review disappears silently and reappears as a system nobody can explain."},"body":{"format":"markdown","text":"## Review was never only about defects\n\nAsk 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.\n\nSpecifically, four things happened in a review that had nothing to do with finding bugs:\n\n- A second person acquired a working model of a part of the system they did not write.\n- Conventions propagated, because someone said \"we usually do this the other way\" and a reason came with it.\n- Newer people learned by watching what senior people noticed.\n- The bus factor went up by one for that area of the code.\n\nEvery 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.\n\n## What broke\n\nThe author's half is no longer guaranteed.\n\nA 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.\n\nWhen 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.\n\n## Four practices that put it back\n\n**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.\n\nWhat 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.\n\n**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.\n\n**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.\n\n**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:\n\n> 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.\n\nThat 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.\n\n## What this costs\n\nAll 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.\n\nThe 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.\n\nThe 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."},"check":{"question":"A team's defect rate is stable and review turnaround is fast, but after two years no one can explain how the notification service works, including the people who submitted most of its changes. What does this indicate about their review process?","options":[{"text":"The reviews were too shallow to catch defects, and the stable defect rate is a lagging measure that will worsen over the next year.","correct":false,"tempting":"Predicts a defect signal that the evidence contradicts; the failure here is real and produced no defect signal at all."},{"text":"The service lacks documentation, and the remedy is a written architecture guide maintained alongside the code.","correct":false,"tempting":"Proposes an artefact as a substitute for understanding; documents describe a system, they do not give anyone a working model of it."},{"text":"The defect-finding half worked and the knowledge-transfer half did not, because that half needs the author to understand it too.","correct":true},{"text":"Reviewer rotation was insufficient, so expertise concentrated in a few people rather than spreading across the team.","correct":false,"tempting":"Describes concentrated knowledge, but here nobody holds it, including the people who never rotated away."}]},"prev":{"slug":"reviewing-dependency-changes","title":"Reviewing a dependency change","url":"https://addaly.com/learn/how-software-changed/reviewing-dependency-changes"},"next":{"slug":"machine-assisted-review","title":"Letting a machine help you review","url":"https://addaly.com/learn/how-software-changed/machine-assisted-review"},"authorship":"Founder and series editor: Dr Mustafa Mun. Written by AI models to a written standard. Exam keys checked blind by a second model: 3,665 of 3,666 agreed. Academic review invited.","review":{"status":"Draft, open for academic review"},"cite":"Addaly (2026) 'The second job of review, and how it broke', in How Software Development Changed. Edited by M. Mun. Addaly. Available at: https://addaly.com/learn/how-software-changed/review-as-knowledge-transfer (Accessed: 13 October 2026).","licence":{"name":"CC BY-NC-SA 4.0","url":"https://creativecommons.org/licenses/by-nc-sa/4.0/"},"reader":{"schema":1,"title":"The second job of review, and how it broke","courseTitle":"How Software Development Changed","module":{"index":2,"slug":"reading-what-you-did-not-write","title":"Reading what you did not write"},"answer":null,"keyIdea":"Review transferred understanding only because both people had thought hard about the change, so when the author has not, the knowledge-transfer half of review disappears silently and reappears as a system nobody can explain.","hero":{"kind":"plate","image":null,"alt":null,"caption":null},"blocks":[{"t":"h2","id":"review-was-never-only-about-defects","runs":[{"text":"Review was never only about defects"}]},{"t":"p","runs":[{"text":"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."}]},{"t":"p","runs":[{"text":"Specifically, four things happened in a review that had nothing to do with finding bugs:"}]},{"t":"ul","items":[[{"text":"A second person acquired a working model of a part of the system they did not write."}],[{"text":"Conventions propagated, because someone said “we usually do this the other way” and a reason came with it."}],[{"text":"Newer people learned by watching what senior people noticed."}],[{"text":"The bus factor went up by one for that area of the code."}]]},{"t":"p","runs":[{"text":"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."}]},{"t":"h2","id":"what-broke","runs":[{"text":"What broke"}]},{"t":"p","runs":[{"text":"The author’s half is no longer guaranteed."}]},{"t":"p","runs":[{"text":"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."}]},{"t":"p","runs":[{"text":"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."}]},{"t":"h2","id":"four-practices-that-put-it-back","runs":[{"text":"Four practices that put it back"}]},{"t":"p","runs":[{"text":"The walkthrough, not the approval.","b":true},{"text":" 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."}]},{"t":"p","runs":[{"text":"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."}]},{"t":"p","runs":[{"text":"Reverse review.","b":true},{"text":" 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."}]},{"t":"p","runs":[{"text":"Rotate the reviewer, not just the author.","b":true},{"text":" 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."}]},{"t":"p","runs":[{"text":"Write the why in the pull request, not in the code.","b":true},{"text":" A description that says "},{"text":"what changed","i":true},{"text":" is redundant with the diff. A description that says "},{"text":"what else was considered and rejected","i":true},{"text":" is the only place that information will ever exist. Three sentences:"}]},{"t":"quote","runs":[{"text":"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."}]},{"t":"p","runs":[{"text":"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."}]},{"t":"h2","id":"what-this-costs","runs":[{"text":"What this costs"}]},{"t":"p","runs":[{"text":"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."}]},{"t":"p","runs":[{"text":"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."}]},{"t":"p","runs":[{"text":"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."}]}],"check":{"question":[{"text":"A team’s defect rate is stable and review turnaround is fast, but after two years no one can explain how the notification service works, including the people who submitted most of its changes. What does this indicate about their review process?"}],"options":[{"text":[{"text":"The reviews were too shallow to catch defects, and the stable defect rate is a lagging measure that will worsen over the next year."}],"correct":false,"tempting":[{"text":"Predicts a defect signal that the evidence contradicts; the failure here is real and produced no defect signal at all."}]},{"text":[{"text":"The service lacks documentation, and the remedy is a written architecture guide maintained alongside the code."}],"correct":false,"tempting":[{"text":"Proposes an artefact as a substitute for understanding; documents describe a system, they do not give anyone a working model of it."}]},{"text":[{"text":"The defect-finding half worked and the knowledge-transfer half did not, because that half needs the author to understand it too."}],"correct":true,"tempting":null},{"text":[{"text":"Reviewer rotation was insufficient, so expertise concentrated in a few people rather than spreading across the team."}],"correct":false,"tempting":[{"text":"Describes concentrated knowledge, but here nobody holds it, including the people who never rotated away."}]}],"order":[1,3,0,2],"why":null},"prev":{"slug":"reviewing-dependency-changes","title":"Reviewing a dependency change","minutes":9},"next":{"slug":"machine-assisted-review","title":"Letting a machine help you review","minutes":9}}}