The artefact a review produces — recognising that the template's scope statement, severity-classified findings, actionable per-finding messages, documented decisions with named authority, captured reviewer-author dialogue, and outcome-traceability to system change are what determine whether the review document is a binding decision artefact or a record of meetings that didn't actually resolve anything.
This page is about the review document template — the specific structured artefact that captures the result of an architecture review, design review, or other formal evaluation. The discipline of how reviews work as governance instruments — when reviews are required, who reviews, what authority reviews carry, how reviews integrate with the team's decision flow — lives in governance/review-templates and the broader governance section. Same family, different operational concern: this page owns the document; governance owns the meta-discipline.
A primitive review document is what gets produced when "we should write up the review somewhere": meeting notes that capture some of the discussion, a list of issues raised that may or may not be ranked by importance, an implicit decision communicated by the absence of objection. The reviewer's concerns get partially captured; the author's responses get partially captured; the decision to proceed or revise is implicit; the relationship between the review and the system changes that followed is unrecoverable. Six months later, when someone asks "why did we accept that approach despite the security concern raised in review?" — the review document doesn't say.
A production review document is a designed artefact with structured fields. Its scope statement at the top defines what's being reviewed, against what criteria, at what depth — so the reader can calibrate what the review covered and what it didn't. Its findings are classified by severity with a documented vocabulary (blocker / significant / minor / observation) and explicit criteria for each tier — so future readers can distinguish concerns the reviewer flagged as must-address from concerns flagged as nice-to-address. Each finding is actionable: what the issue is, where it occurs (specific reference into the system or design), and what to do about it — not vague concerns but specific issues with specific resolution paths. The decision is documented with named decision authority and rationale: proceed / proceed-with-changes / defer / reject; who decided; why. The reviewer-author dialogue is captured — not just the findings, but the back-and-forth that produced the decision, including objections raised, counterarguments, and resolutions reached. The outcome traceability links the review to specific system changes: what got fixed (with PR links), what was deferred to follow-up (with ticket links), what was accepted as-is (with explicit acknowledgement and rationale).
The architectural shift is not "we have review documents." It is: the review document is a designed artefact whose scope statement, severity-classified findings, actionable findings, decisions with named authority, dialogue capture, and outcome traceability determine whether the review's work survives the review meeting or evaporates into folklore — and treating the document as meeting notes produces a corpus where the team's accumulated review judgment can't be recovered when needed.
A review document without a scope statement leaves the reader (and especially the reader who wasn't in the review meeting) unable to calibrate what the review actually covered. Was this a security review or a general architecture review? Did the reviewer evaluate operability? Did the reviewer have access to the runtime configuration, or only to the design document? The architectural discipline is to open the document with an explicit scope statement that addresses three dimensions: what's being reviewed (the system / design / change / specific subsystem), against what criteria (which dimensions: architecture, security, operability, scalability, cost — typically with a checklist or framework name), and at what depth (design-document review only, code review with a sample of files, architecture deep-dive with the team, runtime evaluation in a staging environment). Without scope, the absence of findings doesn't tell readers whether the topic was clean or whether it wasn't examined.
checklists/architecture, team-specific standards).Pick a recent review document in your organisation. Reading only its scope section, can you tell what was reviewed, against what criteria, at what depth? If the scope is implicit ("review of the new payment service") rather than explicit (system + version + criteria + depth), the document leaves future readers unable to interpret what the review's silence on a topic actually means.
ATAM — Architecture Tradeoff Analysis Method treats scope-explicit review as a primary discipline; the canonical ATAM evaluation begins with documented scope. ARID — Active Reviews for Intermediate Designs similarly opens with explicit scoping.
A finding marked simply "issue" tells the reader nothing about how seriously to take it. The author confronted with a list of unranked findings either treats them all as urgent (over-respond) or treats them all as minor (under-respond); without ranking, the reviewer's calibration is lost. The architectural discipline is severity classification with a documented vocabulary and explicit criteria. Blocker: the finding must be addressed before the change proceeds; the change should not ship until resolved. Significant: the finding should be addressed; ignoring it incurs material risk; the change can proceed only if the team explicitly accepts the risk with rationale. Minor: the finding should be addressed but isn't urgent; the change can proceed and the finding becomes follow-up work. Observation: the finding is informational; no action required. Each tier's criteria are documented at the team or organisation level; reviewers calibrate against the same scale; readers can interpret the severity without re-litigating each finding.
Pick a recent review document. Are findings classified by severity, with the severity vocabulary documented? If findings are unranked or ranked subjectively, the document is forcing every reader to re-evaluate each finding — and the calibration the reviewer applied is being lost in transmission.
Google Engineering Practices Documentation covers severity-classified review at code-review level; the discipline transfers to architecture review. ATAM — Architecture Tradeoff Analysis Method operationalises severity classification through risk-themed analysis.
A finding stated as "concerns about scalability" tells the author that the reviewer is concerned but not what specifically to address. The author's response is to either ask the reviewer for more detail (scheduling cost) or guess and re-submit (rework cost). The architectural discipline is to write findings with three explicit elements: what's wrong (the specific issue, in language the author can act on), where (specific reference into the artefact under review — design section number, code file, configuration line, architecture component), what to do about it (the proposed resolution, even if the resolution is "evaluate alternatives X and Y"). The discipline pays compound returns: actionable findings get fixed; vague findings don't, and re-surface in the next review.
Pick a recent review document. Pick three findings. For each, are the issue, location, and recommendation all explicit? If findings are vague ("scalability concerns") or have no recommendation ("fix this somehow"), the author is forced to interpret the finding before they can act on it — and interpretation costs that compound across many findings.
Google Engineering Practices Documentation treats actionable feedback as a primary code-review discipline; the discipline transfers to architecture review at framework level.
A review meeting that ends with "the team will think about it" or "we'll see how it goes" hasn't actually decided anything. The author leaves the meeting unsure what was agreed; future readers can't tell what was decided versus what was discussed. The architectural discipline is explicit decision documentation: each review concludes with one of a small set of documented decisions — proceed (the change ships as proposed), proceed with changes (the change ships after specific findings are addressed; the changes are listed), defer (the change is paused until specific conditions are met; the conditions are listed), reject (the change is not adopted; the reason is documented). The decision is attributed to a named decision authority — the architect, the reviewer, the team lead, the architecture review board — depending on the team's governance. The rationale is captured: why this decision was reached, particularly when it goes against any reviewer's recommendation.
Pick a recent review document. What was the decision, who decided, and what was the rationale? If any of these is implicit ("the team felt it was probably fine"), the document hasn't recorded a decision — and future readers can't tell whether the change was authorised or whether nothing was actually agreed.
ATAM — Architecture Tradeoff Analysis Method treats decision documentation as central to architectural review. The same discipline applies to lighter-weight design reviews.
A review document that captures only the findings and the final decision misses an important layer: the dialogue between reviewer and author that often produced the resolution. The reviewer raised a concern; the author responded with context or a counter-proposal; the reviewer either accepted the response or refined the concern; eventually a resolution was reached. The resolution alone tells the reader what was decided; the dialogue tells them why. Future readers facing similar concerns benefit enormously from seeing how the original reasoning unfolded — including responses that were considered and rejected. The architectural discipline is to capture this dialogue alongside the findings, either as threaded comments on each finding or as a discussion section that walks through the major exchanges.
Pick a recent review document. Was substantive disagreement captured (a finding the author disputed), or only the findings the author accepted? If disagreement isn't visible, the document is showing the consensus output but hiding the reasoning that produced it — and future readers can't tell what was knowingly accepted versus what was overlooked.
Google Engineering Practices Documentation treats reviewer-author dialogue capture as central to code review; the principles extend to architecture review.
A review document that ends with "decision: proceed with changes" but never confirms whether the changes were actually made is incomplete. Six months later, the team that needs to know whether the security finding from review actually got addressed has no way to tell — the review says it was supposed to be addressed; the system either was or wasn't changed; the linkage is missing. The architectural discipline is outcome traceability: each finding's resolution is linked to specific system changes (PR URLs, commit hashes, deploy records) for things that were fixed; ticket links for things that were deferred to follow-up work; explicit "accepted as-is" annotations for findings that the team decided not to act on, with the rationale recorded. Outcome traceability turns the review document into a binding contract whose fulfilment is auditable.
Pick a review from six months ago in your organisation. Walk its findings: for each, can you tell whether it was fixed, deferred, or accepted as-is? If the linkage is missing, the review's recommendations didn't have a closing mechanism — and the team that depended on those recommendations being addressed has no way to verify they were.
The outcome-traceability discipline transfers from code-review practice (Google Engineering Practices Documentation) to architecture review. Backstage — Software Catalog and similar tools operationalise traceability between review documents and the system changes they produced.
The diagram below shows the canonical structure of a review document as a class diagram: a Review aggregates Scope, Findings (each with Severity, Location, and Recommendation), Dialogue threads, a Decision (with named authority and rationale), and Outcome traceability links to system changes. The document is a structured artefact whose fields determine whether the review's work survives the meeting.
The review document doesn't say what was reviewed, against what criteria, at what depth. The absence of findings on a topic could mean it was examined and found clean, or it could mean it wasn't examined at all.
Explicit scope statement at the top: artefact under review with version, criteria evaluated (with framework reference), depth of review. Out-of-scope dimensions explicitly noted.
Findings are listed without severity classification. The author treats all findings as equally urgent (over-respond) or equally minor (under-respond). The reviewer's calibration is lost.
Severity vocabulary documented at organisation level (blocker / significant / minor / observation). Each tier has criteria. Findings tagged with severity, formatted for visual distinction.
"Scalability concerns" / "consider security implications" / "could be cleaner." The author doesn't know what specifically to address or what good would look like.
Each finding has three elements: what's wrong, where (specific reference), what to do (recommended resolution). If no recommendation exists, express as a question rather than a finding.
The review meeting ended with discussion but no documented conclusion. Future readers can't tell what was actually decided.
Documented decision from a small vocabulary (proceed / proceed-with-changes / defer / reject), attributed to named authority, with rationale. For "proceed with changes," required changes are listed explicitly.
The review said the change should ship after addressing finding X. Did it? The document doesn't say; the system either was or wasn't changed; the linkage between recommendation and outcome is missing.
Each finding's resolution linked to system changes (PR, commit, deploy) for fixes; ticket links for deferrals; explicit "accepted as-is" with rationale for findings the team decided not to act on. The review becomes an auditable contract.
Out-of-scope dimensions explicitly noted. The reader can calibrate what the review covered without inference.
Blocker / significant / minor / observation, with documented criteria per tier. Reviewers calibrate against the same scale.
Specifics rather than vague concerns. The author can act on the finding without interpretation cost.
All blockers can be visually located at a glance. The document's structure surfaces the most important findings first.
Each option's meaning is documented at organisation level. The decision is binary, not a discussion summary.
Team / individual / review board, depending on governance. The decision can be attributed and audited.
Proceeding despite a blocker is a documented choice, not an oversight. The rationale is recoverable for future readers.
The reasoning behind the decision is visible. Future readers see what was knowingly accepted versus what was overlooked.
Outcome traceability is closed-loop. The review becomes an auditable contract.
The template is governance-controlled; new reviews follow the same structure. The corpus is consistent across time and reviewers.
Other substantive pages in the library that link here: