The engineering code review culture decision record: why the review culture model you chose determines your knowledge diffusion rate and your defect escape surface

A 12-person startup had been building its product for two years with a code review process that its founding team described as rigorous: every PR required at least one approval before merging, PRs were expected to include a description of what changed and why, and the founding engineers — three of whom had come from larger companies with formal review processes — took review seriously and left substantive comments on each other's work. The process had worked well at five people, when the three founders and two early hires had collectively read most of the codebase and review was as much a conversation about the code as a gate on it. At twelve people, the process had accumulated several changes that no one had explicitly decided on: the founding engineers, whose time was increasingly consumed by architecture calls and hiring conversations, had begun approving PRs from the newer engineers with fewer comments — not because the code quality had declined but because the founding engineers no longer had the context to engage deeply with areas of the codebase they were not actively building; the newer engineers, seeing that PRs from founding engineers received thorough engagement and PRs from newer engineers received quick approvals, had calibrated their review behavior to match what they received rather than what they had observed the founders exchange; and the PR description norm had drifted from explaining the reasoning behind a change to describing what the change did, which was already visible in the diff.

In eighteen months, the startup hired a new engineering lead from a mid-size company with a formal review process, who spent her first month reading the codebase. Her observation to the CTO in their first one-on-one was that the authentication and billing code — two of the three highest-risk areas of the codebase — appeared to have been written almost entirely by the founding engineer who built them, reviewed primarily by that same engineer's close collaborators in the early months, and not meaningfully reviewed by any of the seven engineers hired in the prior year. The git log showed that the authentication module had received exactly four substantive reviewer comments in the last twelve months, all from the same two engineers. The founding engineer who had written the authentication system had left the company six months earlier to join a late-stage startup. The new engineering lead's first direct report, an L4 engineer assigned to fix an authentication bug, spent three weeks reverse-engineering the design intent from the code before making the change — not because the code was poorly written, but because the design intent that had been obvious to the founding engineer had never been transferred to anyone else through the review process, and the engineering lead had no one she could ask who understood the original reasoning. The six-week estimate for the fix had been three weeks of orientation to code whose design had been reviewed but not understood by any currently-employed engineer, and three weeks of the actual change. The CTO's post-mortem question — "why didn't we catch this in review?" — had the wrong frame: the review process had processed every commit. What it had not done was diffuse knowledge.

A 52-person B2B SaaS had a code review process it had run without significant changes for three years: one approval required for most PRs, two required for changes to the payments and authentication systems. After a production incident in which a logic error in the order processing service caused incorrect charges to be applied to approximately 400 customer accounts — an error that passed the test suite and received a one-approval review — the VP of Engineering mandated a new policy: all PRs require approval from two engineers, at least one of whom must be a senior engineer (L5 or above). The policy was announced in the engineering all-hands. No accompanying guidance was provided about what a senior engineer was expected to evaluate in a review, what distinguished a thorough review from a cursory one, or how the increased review load would be managed given that there were seven senior engineers across four teams. The policy went into effect the following Monday.

Within three weeks, the throughput constraint was visible in the metrics: the median time from PR open to merge had increased from 18 hours to 61 hours, driven almost entirely by the wait for a required senior engineer to process the review. The seven senior engineers, who had each been receiving an average of three to four review requests per day before the policy, were now receiving eight to twelve. In standup conversations, senior engineers began to describe code review as the primary source of interruption in their work day. The pattern that emerged over the following two months was predictable: senior engineers began processing the review queue in two sessions per day rather than continuously, which reduced the interruption cost but did not reduce the volume; within each session, the time per review was compressed to match the session length against the queue depth; and the reviews themselves shifted from substantive engagement to a fast scan for obvious errors and a check that the PR description matched the diff. Three months after the policy change, a senior engineer on the payments team conducted an informal audit: she pulled the last forty PRs that had received two senior approvals on her team and read each of them at the depth she believed a thorough review required. She found that twelve of the forty — thirty percent — had architectural or integration-level issues that she believed would have been caught if reviewed at that depth, issues that had not produced production incidents yet but that represented latent risk in the codebase. The two-approval policy had produced confidence in review quality that the review process was not providing. The most significant case in her audit was a refactor of the payment reconciliation service: 1,847 lines across 31 files, submitted two days before a quarter-end sprint close, approved by two senior engineers within four hours of submission, with a total of three reviewer comments — all on variable naming. The refactor had introduced a race condition in the reconciliation loop that would surface only under concurrent high-volume processing, a condition that did not appear in the test suite and that was visible only to a reviewer who had read the reconciliation service's assumptions about transaction ordering in the adjacent processing code that the diff did not touch.

An 87-person enterprise SaaS had, by any conventional measure, a mature engineering quality culture. Its CI/CD pipeline ran 14,200 automated tests in under nine minutes, with an 84% line coverage threshold enforced as a merge gate. A static analysis suite caught 23 categories of common vulnerability patterns. A dependency scanning tool flagged known CVEs before they reached main. The engineering blog had published a post on the review culture that had received favorable comments from the engineering community: reviewers were expected to check for test coverage, security implications, performance considerations in hot paths, and adherence to the team's style guide. The post had been written by a senior engineer who was genuinely proud of the review process and whose description of it was accurate to what the team practiced.

In the eighteen months following the blog post, the organization experienced three significant production incidents, each of which traced back to the same category of defect. In the first incident, an engineer had modified the behavior of a function in the notification service that was called by both the email delivery pipeline and the event processing pipeline; the function's new behavior was correct for the email pipeline use case that had motivated the change, and the tests for that use case all passed; the event pipeline made an assumption about the function's behavior that the change violated, an assumption that was not expressed in the tests for the function but that was visible in the event pipeline's own code, which the reviewer had not read. The incident produced a four-hour outage for one customer segment. In the second incident, an engineer had added a caching layer to a user preference lookup used in three different flows; the cache's invalidation behavior was correct for two of the three flows, and tests for those flows passed; the third flow, which used the same lookup in a context where stale data produced a security-relevant outcome, was not covered by the tests for the preference lookup itself — it was covered only by an integration test in the third flow's own test suite that required the cache to be disabled to run correctly, which the CI pipeline did not do. The incident produced a 36-hour period during which a subset of users could access preference settings that should have been inaccessible after a permission change. In the third incident, the defect category was identical: a change that was locally correct and passed all automated tests violated a system-level assumption that was expressed in adjacent code the reviewer had not read. After the third incident, the VP of Engineering commissioned a review culture retrospective. The retrospective's central finding was that the organization's review culture had evolved into a human verification layer for the automated quality gates: reviewers had calibrated their review scope to the categories the automated tools did not cover, but the calibration had drifted toward the categories that were easy and familiar — naming, style, test coverage count — and away from the categories that were genuinely complementary to the automated layer, specifically integration correctness and system-level contract validation. The automated tools were excellent; the human review layer had stopped covering the territory the automated tools could not reach, and the three incidents had each occurred in exactly that territory.

Structural properties set by the engineering code review culture decision

Two structural properties are determined by the founding decisions about review purpose, scope, participation, and depth expectations. Both are invisible when the engineering organization is small enough that knowledge propagates through proximity — engineers hear about decisions in standup, read PRs out of curiosity, and accumulate codebase knowledge through osmosis — and visible when the organization has grown large enough that the review process is the primary mechanism through which engineers learn what is changing in systems they do not actively work in.

Property 1: Knowledge diffusion rate. The knowledge diffusion rate is the rate at which understanding of each area of the codebase propagates from the engineers who originally built it to the engineers who interact with it later — bounded by three factors. First, review breadth: the fraction of engineers who have engaged with each system area at sufficient depth through review to hold a working model of its design intent, its invariants, and its failure modes. A codebase where 90% of the review engagement on the authentication system has been performed by the two engineers who built it is a codebase whose authentication design knowledge is owned by two people; the departure of either represents an onboarding cost for their replacement that is not a function of code quality or documentation quality but of how few minds have engaged deeply with the code. Review breadth is determined by the participation model — whether the organization rotates reviewers deliberately to ensure coverage breadth or assigns reviewers by proximity and convenience, which concentrates review on the engineers already familiar with each area and produces the pattern where the engineers who know the code best are the ones who most frequently review it, reinforcing rather than diffusing the knowledge concentration. Second, review depth: the quality of engagement, whether reviewers are understanding the design intent of the change or only verifying that the changed lines look reasonable. A reviewer who understands why an abstraction was chosen, what invariant a function protects, and what the change assumes about the calling context has acquired knowledge that is transferable; a reviewer who has confirmed that the code style is consistent and that tests are present has confirmed that the code looks correct and has acquired no transferable understanding of why it was written the way it was. Review depth is determined by the explicit model of what a review is for: organizations that have articulated review as a knowledge-sharing function produce reviewers who attempt to understand the change; organizations that have articulated review as a defect-detection gate produce reviewers who attempt to find errors; organizations that have no explicit articulation produce reviewers who do whatever minimizes the time to approval, which is the surface scan that confirms the code looks reasonable. Third, review retention: whether insights acquired during review are crystallized into forms that outlast the review session — code comments that explain why a design decision was made, documentation that captures a non-obvious invariant that came up in review, a decision record that records the trade-off a reviewer raised and how it was resolved. Review cultures that treat the review comment thread as the repository of review insights produce teams where the insights are accessible only to engineers who can find and read the PR thread, which in practice means they are accessible only to engineers who know to look for them, which is the engineers who already understand the area — exactly the engineers for whom the insight was not new. Connect this to the engineering documentation standards decision record: review and documentation are complementary knowledge diffusion mechanisms, and the decision about which knowledge is expected to live in review comments versus in permanent documentation versus in code comments determines whether the knowledge that is generated through the review process accumulates into a form the organization can build on or evaporates with each passing sprint.

Property 2: Defect escape surface. The defect escape surface is the set of defect categories that the review process is not reliably catching before production — bounded by three factors. First, review coverage model: the explicit or implicit division of responsibility between automated tools and human reviewers, and whether that division has gaps in defect categories that neither layer catches reliably. An organization that has invested heavily in automated quality gates and treats human review as the verification layer for those gates has designed a review process that is redundant with its automation and leaves the defect categories that automation cannot catch unaddressed. Automated tools are excellent at detecting algorithmic correctness defects — whether the code behaves as the tests describe — but are structurally limited at detecting integration correctness defects — whether the code's behavior satisfies the contracts that calling code depends on — because integration correctness requires understanding the calling context, which automated tests can only partially simulate. The third story's organization had an 84% line coverage threshold; the defects that caused its production incidents all occurred at integration boundaries that were covered by tests in one direction but not the other. The coverage model worked; the model was optimized for the wrong defect category. Second, review scope completeness: whether reviewers read only the changed lines or the code that those lines interact with. A reviewer who reads only the diff evaluates the change in isolation; a reviewer who reads the changed lines and the functions that call them, the state those functions pass in, the contracts the changed function must satisfy, and the adjacent code that relies on the changed function's behavior evaluates the change in context. The difference between these two engagement scopes is exactly the difference between a review that would and would not have caught each of the defects in the third story's production incidents — in each case, the defect was invisible in the diff and visible in the adjacent code the reviewer did not read. Most review cultures do not have an explicit model of how much context beyond the changed lines a reviewer is expected to read, which means the answer is determined by individual reviewer judgment and defaults to the diff because the diff is what the review tool presents. Third, defect taxonomy alignment: whether the organization's review process is designed to catch the category of defects that its production incident history shows are most costly, or whether it is designed around the categories that reviewers feel most competent to evaluate. Organizations that have not analyzed their incident history against their review model typically over-invest in reviewing for the defects that are easiest to discuss in a review comment — naming, style, missing error handling, test coverage — and under-invest in reviewing for the defects that are hardest to articulate — integration assumptions, system-level invariants, design-level trade-offs — which are disproportionately the defects that produce the most expensive production incidents. Connect this to the engineering technical strategy decision record: the review culture is an expression of the technical strategy's quality philosophy; an organization whose technical strategy specifies that system-level reliability is the primary engineering quality target needs a review culture that prioritizes integration correctness over algorithmic correctness, and a review culture that was designed before that strategic commitment was made will need to be explicitly redesigned to align with it — the strategy and the review culture cannot be incoherent without one of them being ineffective.

The engineering code review culture ADR: five sections

Section 1: Code review purpose and scope model. The purpose and scope model specifies what review is for, what categories of issues reviewers are expected to find, what categories are owned by automated tools, and how the scope model is communicated to reviewers so they share a common understanding of what "good review" means. The most consequential decision in this section is not the choice between defect-catching, knowledge-sharing, and design-alignment purposes — most organizations want all three — but the explicit ranking of those purposes when they create tension, and the explicit communication of that ranking to reviewers. A review culture that articulates defect-catching as the primary purpose and knowledge-sharing as secondary produces reviewers who optimize their time for finding errors and treat knowledge transfer as a bonus if there is time; a culture that articulates knowledge-sharing as primary produces reviewers who spend time understanding the change and its context, which is slower per review but produces the breadth and depth of codebase understanding that pays off when those reviewers need to triage an incident or onboard a new engineer. The scope model should also specify the explicit boundary between what automated tools are responsible for catching and what human reviewers are responsible for catching — not as a permission to skip the automated-tool categories in review, but as an explicit articulation of the categories where human review adds value that automation cannot. An organization that has not specified this boundary produces reviewers who fill their review attention with the categories the tools cover, because those are the categories the tools have already analyzed and the analysis is visible in the CI feedback — the reviewer is drawn to the pre-analyzed territory rather than the territory that requires original scrutiny. The scope model should also address what is not in scope for review: whether reviewers are expected to evaluate product decisions visible in the code, whether architecture feedback is in scope or is handled through a separate design review process, and how reviewers should handle cases where the right change is the one that would require a larger refactor than the PR contains — giving feedback that cannot be addressed in the current PR is either valuable design input or a source of frustration depending on whether the review culture has a norm for how that feedback is documented and carried forward. Connect this to the engineering API design philosophy decision record: design-level review — the category of review that evaluates whether the API surface a change introduces is consistent with the organization's API design philosophy — is the mechanism by which the written philosophy propagates from document to behavior; an organization that has a clear API design philosophy but no review culture that makes design-level review an explicit scope item will find that the philosophy is followed by the engineers who read it and ignored by the engineers who did not, with no correction mechanism at the point where the deviation occurs.

Section 2: Review participation and coverage model. The participation and coverage model specifies who reviews what, how reviewer assignment is structured, and how the model ensures review breadth — that knowledge of each system area propagates to engineers outside the team that built it — rather than concentrating review on the engineers already most familiar with each area. The most consequential decision in this section is not the assignment mechanism (round-robin, proximity-based, expertise-based) but the explicit acknowledgment that a proximity-based assignment model — assigning reviews to the engineers most familiar with the changed code — is a knowledge concentration model rather than a knowledge diffusion model, and that the two goals are in direct tension. Proximity-based assignment produces the highest short-term review quality per review because the reviewer brings existing context; it also produces the codebase ownership pattern where knowledge of each system area is held by the same small set of engineers who have always held it, because the review process consistently returns to those engineers rather than expanding the set. An organization that has not explicitly decided between these models will default to proximity-based assignment because that is the lowest-friction path — the engineer who knows the code is the engineer who can review it fastest — and will produce concentrated knowledge until a departure forces the issue. The participation model should also specify how the coverage model handles high-traffic code areas — authentication, billing, core data models — where concentrated knowledge creates the highest organizational risk. These are typically the areas that are most frequently changed, where the ownership concentration is most pronounced, and where an explicit deliberate rotation policy is most valuable. The model should specify at what review frequency an engineer can be considered to have developed working knowledge of a system area, and what the minimum coverage target is — the number of engineers outside the original team who should hold working knowledge of each critical area. Connect this to the engineering technical roadmap communication decision record: the review coverage model is the engineering organization's mechanism for managing the knowledge risk that the roadmap communication model implicitly creates — when the roadmap communicates that a critical system area is scheduled for significant work, the review coverage model should be updated to ensure that the engineers who will review that work have sufficient context to review it at depth, which requires deliberate coverage expansion before the work begins rather than reactive coverage expansion after an incident reveals the gap.

Section 3: Review depth and engagement model. The review depth and engagement model specifies what depth of engagement is expected for different categories of changes, how depth is calibrated against review capacity, and what the explicit expectations are for how much code context a reviewer is expected to read beyond the changed lines. The most consequential decision in this section is the scope model for context reading: whether reviewers are expected to read only the diff, the diff plus the functions that call the changed code, or the diff plus the full module context. The right answer varies by change category — a localized bug fix that changes three lines in a well-tested utility function does not require reading the calling context; a change to a function that is called in multiple flows, modifies shared state, or establishes a contract that other code relies on requires reading the calling context to evaluate the change correctly — and an organization that has not specified this variation will produce reviewers who apply a uniform scope model (usually diff-only) to all changes, which is appropriate for the low-risk category and insufficient for the high-risk category. The depth model should include an explicit definition of the code a reviewer is expected to read for different change categories: for a change to a public function, the reviewer should read the function's callers; for a change to shared state, the reviewer should read all locations where the state is read and written; for a change to a service boundary, the reviewer should read the contract the service presents to its callers and verify the change is consistent with it. This specification sounds burdensome but is typically a ten-minute investment for the changes where it matters; the reason it is not standard practice is that it has not been articulated as an expectation, not that it requires excessive time. The depth model should also specify how review depth expectations are adjusted when review capacity is constrained — when an engineer is receiving more review requests than they can process at the specified depth, what is the right response: declining some reviews, requesting extended turnaround time, or reducing depth. Organizations that do not specify this tradeoff produce engineers who reduce depth without acknowledging it, which produces the second story's outcome: the appearance of thorough review without the substance. Connect this to the engineering API design philosophy decision record: the review depth model for API changes should be calibrated to the breaking change taxonomy in the API design philosophy — the categories of change that the philosophy identifies as highest-risk for backward compatibility are exactly the categories that require reading the calling context, because breaking changes are often invisible in the diff and visible only to a reviewer who understands how the changed surface is used by its callers.

Section 4: Review quality and accountability model. The review quality and accountability model specifies how the organization measures review quality, what the feedback loop is when a defect escapes through a review that should have caught it, and how the organization improves its review culture over time rather than allowing it to calcify into whatever norms emerged from the first two years. The most consequential decision in this section is the feedback loop design: whether the organization has a process for connecting production incidents back to the review that approved the change that introduced the defect, analyzing what the reviewer would have needed to know or look at to catch the defect, and using that analysis to update the review culture. Organizations that do not have this feedback loop make their review culture impervious to learning from incidents: the incident retrospective identifies the defect, the fix is deployed, and the review culture that allowed the defect to pass is unchanged because the retrospective does not include an explicit step that asks "what would a thorough review of this PR have looked like, and did our review process produce that?" The organizations that have improved review quality over time have typically built this feedback step into their incident retrospective process — not as blame allocation but as review culture calibration — and have used the output to update their review checklists, scope models, and depth expectations. The quality model should also specify how review quality is visible: whether there are leading indicators (review comment depth, review turnaround by category, reviewer breadth per module) that the organization tracks to detect degradation before it produces incidents, or whether quality is measured exclusively by lagging indicators (defect escape rate, incident severity). Lagging-indicator-only quality measurement produces organizations that are perpetually reacting to the most recent incident rather than building toward a review culture that does not produce that class of incident. Connect this to the engineering technical strategy decision record: the review quality model is one of the engineering organization's primary mechanisms for sustaining technical quality as the team grows; an organization whose technical strategy specifies quality targets — reliability SLAs, security posture, architecture coherence — needs a review quality model that connects those targets to review practice, because the review process is the point in the development workflow where quality targets are either enforced or not, and a review culture that was designed before the quality targets were articulated will not enforce them without explicit redesign.

Section 5: Review tooling and automation boundary model. The tooling and automation boundary model specifies which automated quality gates are in place, what categories of defects each gate is designed to catch, how the tooling is calibrated to avoid substituting for human review depth rather than complementing it, and how the automation model is updated as the codebase, team, and defect history evolve. The most consequential decision in this section is the explicit articulation of the automation boundary: the set of defect categories for which the organization relies on automated tools as the primary detection mechanism, and the set of defect categories for which automated tools are insufficient and human review is the primary detection mechanism. An organization that has not specified this boundary will have it determined by the behavior of its reviewers, who will unconsciously calibrate their review attention to the territory the tools have not already covered — which in practice means the categories the tools cover most visibly in the CI output, because that is what the reviewer sees. The automation boundary should be specified based on defect category analysis rather than tool capability analysis: the question is not "what do our tools catch?" but "what categories of defects does our production incident history show are most costly, and which of those categories do our tools catch reliably?" Categories that the tools catch reliably should be delegated to the tools with a light human verification layer; categories that the tools do not catch reliably should be explicitly assigned to human review with a depth expectation calibrated to catch them. The tooling model should also address how the automation boundary changes over time: as the test suite matures, as the SAST scanner is tuned, and as the team adds new integration test coverage, the categories that require deep human review should shrink, freeing reviewer attention for the categories that remain beyond automation. An organization that does not have a process for updating the automation boundary will have a review culture that continues to invest human attention in categories the automation now covers, while new defect categories that the automation does not yet cover accumulate in the escape surface. Connect this to the open-source extractor: the reasoning behind automation boundary decisions — why the organization decided that integration correctness is a human review responsibility rather than an automated gate, what incident history motivated that classification, what the known limitations of the current test suite are that make automated integration coverage insufficient for the high-risk system areas — is reasoning conducted in AI chat sessions when engineering leads work through how to restructure the review culture after an incident that automation should have caught but did not; running those sessions through the extractor produces the review culture decision record that allows the next engineering lead to inherit not just the current automation boundary configuration but the analysis that produced it, which is the analysis they need to evaluate whether it should be updated as the codebase and incident history evolve.

FAQ

Further reading

• Engineering technical strategy decision record — the review culture is an expression of the technical strategy's quality philosophy; an organization whose technical strategy specifies that system-level reliability is the primary engineering quality target needs a review culture that prioritizes integration correctness review over algorithmic correctness review, and a review culture that was designed before that strategic commitment was articulated will continue to optimize for the wrong defect category until it is explicitly redesigned; the strategy and the review culture cannot be incoherent without one of them being ineffective, and the review culture is typically the one that loses because it is designed earlier and updated less frequently than the strategy.
• Engineering API design philosophy decision record — design-level review is the mechanism by which the API design philosophy propagates from written principle to team behavior; an organization that has a clear API design philosophy but no review culture that makes design-level review an explicit scope item will find that the philosophy is followed by the engineers who read it and ignored by the engineers who did not, with no correction at the point where the deviation occurs; the review scope model and the API design philosophy must be designed as a coherent system, with the review scope explicitly including evaluation of whether API surfaces introduced by a change are consistent with the design philosophy, so that the philosophy is enforced at the merge gate rather than discovered in a post-launch audit.
• Engineering technical roadmap communication decision record — the review coverage model is the engineering organization's mechanism for managing the knowledge risk that the roadmap creates; when the roadmap communicates that a critical system area is scheduled for significant work in a future quarter, the review coverage model should be updated to ensure that the engineers who will review that work have sufficient context to review it at depth before the work begins; an organization that does not connect its review coverage planning to its roadmap will discover the coverage gap when a complex change to an under-reviewed system area is submitted and the engineers designated as reviewers do not have the contextual understanding to evaluate it at the depth the change requires.
• Engineering documentation standards decision record — review and documentation are complementary knowledge diffusion mechanisms, and the decision about which knowledge is expected to live in review comments versus in permanent documentation versus in code comments determines whether knowledge generated through the review process accumulates into a form the organization can build on or evaporates with each sprint; a review culture that generates insight about design intent in review comments but has no norm for promoting that insight into documentation produces an organization that continuously regenerates the same understanding from source code rather than accumulating it, and the regeneration cost compounds with each engineer who joins the team and must reconstruct the same design context that the founding engineers expressed in review comments that are now six months old and three pages deep in the PR history.
• Open-source extractor — the reasoning behind code review culture decisions — why the organization decided that integration correctness is a human review responsibility rather than an automated gate, what incident history motivated the current review scope model, why the depth expectations were set at the level they were, and what the known failure modes of the current review culture are — is reasoning conducted in AI chat sessions when engineering leads work through how to redesign the review culture after an incident that review should have caught; running those sessions through the extractor produces the review culture decision record that allows the next engineering lead to inherit not just the current review norms but the analysis that produced them, which is the analysis they need to evaluate whether the norms should be updated as the team grows, the codebase evolves, and the incident history shifts.