From Analysis to System Design

Design Reviews & Walkthroughs

18 min Lesson 8 of 10

Design Reviews & Walkthroughs

A design document that has never been scrutinised by anyone other than its author is a design document waiting to fail in production. Design reviews and walkthroughs are the structured, human-led quality gates that catch misalignments between what was specified and what was designed — before a single line of production code is written. The cost of fixing a design flaw at this stage is orders of magnitude lower than fixing the same flaw after development, testing, or deployment.

This lesson teaches you how to plan, facilitate, and act on the two most important pre-build review techniques: the structured walkthrough and the formal design review. You will also learn how to trace every design decision back to a documented requirement — closing the loop that started when you first wrote the System Requirements Specification.

Why Reviews Fail (and How to Prevent It)

Most review failures fall into three categories. First, scope creep in the meeting — reviewers start debating implementation choices rather than evaluating whether the design satisfies the requirements. Second, no pre-read — reviewers arrive without studying the materials, so the session becomes a first-reading exercise with no real critique. Third, no action log — issues are raised verbally, agreed upon in the room, and then forgotten because nobody recorded them with an owner and a deadline.

The antidote is the same for all three failures: a clear review charter that defines scope, a mandatory pre-read window of at least 48 hours, and a formal action register maintained throughout and published immediately after the session.

The Structured Walkthrough

A walkthrough is an informal, author-led review. The designer presents the design to a small group (3–5 people) and narrates it from beginning to end, exactly as a tour guide walks visitors through a building. The audience asks clarifying questions and flags concerns, but the author controls the pace and the agenda.

Walkthroughs are best suited to:

  • Early or draft designs that are still evolving.
  • Sub-systems where only 2–3 stakeholders need visibility.
  • Teams with a high-trust culture who find formal inspections unnecessary overhead.

A practical walkthrough for a clinic appointment booking system might proceed like this. The analyst presents the module decomposition diagram. She narrates how the PatientPortal component calls the AppointmentService API, which in turn queries the SlotRepository. A developer notices that the sequence diagram shows a synchronous call that could time out under load — the design should use an async queue for slot-reservation confirmations. That observation is logged as Action #1: revise appointment-confirmation flow to async; owner: lead architect; due: Friday.

The Formal Design Review

A formal design review (sometimes called a design inspection) is a structured, role-separated process in which a dedicated moderator — not the author — runs the session. Formal reviews apply a defect-detection checklist, track every issue against a severity rating, and produce a signed-off review record that becomes part of the project audit trail.

Typical roles in a formal review:

  • Moderator — plans the session, enforces time-boxing, owns the action register. Ideally an experienced analyst who did not author the design.
  • Author(s) — present and clarify; do not defend. The author listens more than she speaks.
  • Reviewers (2–4) — technical peers, a requirements analyst, and a representative of the team that will test or deploy the system.
  • Scribe — records every issue in real time; can be a reviewer who also takes notes.
The author does not own the meeting. In a formal review the moderator runs the session. The author's job is to answer questions honestly and to resist the urge to justify every decision. Defensiveness shuts down reviewers and causes real defects to go unrecorded.

Review Against Requirements: the Checklist Approach

The most reliable way to ensure a design review adds genuine value is to anchor every check to a numbered requirement. Before the session the moderator prepares a requirements-traceability checklist — a list that maps each functional and non-functional requirement to the design element that is supposed to satisfy it. Reviewers then tick each row: satisfied, partially satisfied, or not satisfied.

For an online logistics platform, the checklist might include rows such as:

  • REQ-007 "The system shall display estimated delivery time within 2 seconds" → mapped to the DeliveryEstimator service and its Redis cache layer → reviewers check: does the design actually include caching, and is the 2-second SLA stated in the API specification?
  • REQ-019 "Only authenticated couriers may update shipment status" → mapped to the AuthMiddleware and the ShipmentController → reviewers check: is the authentication guard applied on the correct endpoints?

Any row that is not clearly satisfied becomes a defect in the action register — not a future discussion topic, but a concrete item that must be resolved before the design is approved.

Design Review Process Flow Preparation Review Session Follow-up Outcome Distribute design docs Build req-traceability checklist Reviewers pre-read (min 48 hrs) Assign roles (mod / author / scribe) Author presents design Walk through req checklist row by row Log each defect with severity (Critical/Major/Minor) Moderator time-boxes and keeps on scope Scribe publishes action register Author resolves each action item Updates design doc and re-runs checklist Moderator verifies critical items closed Approved Proceed to build Conditional Minor fixes only Re-design Critical defects found
The four phases of a formal design review: preparation, session, follow-up, and outcome.

Defect Severity Classification

Not every issue raised in a review carries equal weight. Using a three-level severity scale keeps the team focused on what matters and prevents minor stylistic comments from blocking progress:

  • Critical — a requirement is not satisfied, or the design introduces a security vulnerability, a data-loss risk, or a fundamental architectural contradiction. The design cannot be approved until all critical defects are resolved.
  • Major — the design satisfies the requirement in principle but is ambiguous, incomplete, or likely to cause integration problems. Must be resolved before development begins, but does not block approval if the owner commits to a resolution plan.
  • Minor — a naming inconsistency, a missing label on a diagram, or a note that would improve clarity. The author fixes these at her own discretion; they do not hold up approval.
Timebox the session ruthlessly. A two-hour formal review of a 20–30 page design specification is the industry standard. If the design is larger, split it into sub-system reviews scheduled on consecutive days. A session that runs past two hours loses focus and produces diminishing returns. The moderator should call the meeting at the two-hour mark regardless of whether all checklist rows have been ticked — remaining items become asynchronous review tasks.

The Action Register

The action register is the single most important output of any review. It is a structured log with one row per issue, containing at minimum:

  • ID — a unique sequential number (AR-001, AR-002, …).
  • Description — a clear, unambiguous statement of the problem, not the solution.
  • Severity — Critical / Major / Minor.
  • Requirement reference — the REQ-ID(s) that the defect violates or threatens.
  • Owner — the person responsible for resolving it (usually, but not always, the author).
  • Due date — agreed in the room; not left open-ended.
  • Status — Open / In Progress / Resolved / Verified.

Example rows from an action register for a logistics platform review:

AR-001 | Critical | REQ-007 SLA not reflected in DeliveryEstimator design | Owner: J. Ahmad | Due: 2025-09-15 | Open AR-002 | Major | AuthMiddleware scope unclear: applies to /status PUT only or all /shipments routes? | Owner: R. Patel | Due: 2025-09-15 | Open AR-003 | Minor | ERD entity "Courier" labelled "Driver" in sequence diagram — rename for consistency | Owner: Author | Due: 2025-09-17 | Open
Requirements-to-Design Traceability Checklist Req ID Requirement Summary Design Element Status Severity REQ-007 Delivery time displayed within 2 seconds DeliveryEstimator + Redis cache layer ✗ Not Satisfied Critical REQ-019 Only authenticated couriers may update shipment status AuthMiddleware on ShipmentController ~ Partial Major REQ-024 Patient booking confirmation sent within 30 seconds AppointmentService async queue ✓ Satisfied — REQ-031 GDPR: patient data erasure on request within 72 hrs DataErasureJob (scheduled worker) ✓ Satisfied — REQ-038 Admin can export all orders as CSV ReportController ExportService ✓ Satisfied — 2 of 5 requirements require action before design approval
A requirements-to-design traceability checklist used during a formal review session.

Online Store Case Study: Catching a Critical Gap

An online store is planning a loyalty-points module. The SRS contains REQ-044: "Points balances shall be consistent across all sessions — a customer who earns points on mobile must see the updated balance immediately on web." The design team proposes a simple database read from a loyalty_points table on each page load. A reviewer consulting the checklist asks: "The design shows a single read query, but the SRS requires immediate consistency across sessions. If two sessions write simultaneously — one redeeming and one earning — which wins?" The author realises the design has no optimistic locking or atomic transaction boundary around point operations. This is logged as Critical, the design is revised to use a serialised transaction, and the checklist row is marked satisfied after verification. Without the review, this race condition would have surfaced as a customer-facing bug under load.

Do not combine the review with a design meeting. Reviews evaluate a finished or near-finished design artifact. If the design is still being decided, hold a design workshop first, then schedule the review once the document is stable. Mixing the two roles — co-designing and evaluating — in a single session confuses participants and almost always produces an incomplete action register.

What Happens After the Review

The review is not complete when the meeting ends — it is complete when every Critical and Major action item in the register has been closed and verified. The moderator marks the review as Approved, Approved with Conditions, or Requires Re-review. Only an Approved or Approved with Conditions (where the conditions are minor) status clears the design to enter the build phase. A Requires Re-review verdict means the author must revise the design and submit it for a second formal review — a cost that is still far less than discovering the same defects in system testing.

The signed review record — checklist, action register, and final verdict — is archived as a permanent part of the project documentation. When a requirements audit is performed months later, this record provides traceable evidence that every requirement was consciously evaluated against the design before development began.

Previous Lesson The Design Specification Document
Next Lesson Traceability from Requirements to Design
Back to Course