Design Review Frameworks

Overview

Design review is the practice of examining how a system or feature will be built before the build starts. It occupies the gap between "we've decided to do this" and "we've started writing code" — and that gap is where the most consequential feedback can be given at the lowest cost.

Code review catches implementation errors. Design review catches architectural errors: the wrong abstraction, the unexamined scalability assumption, the cross-team dependency that was never negotiated, the data model that cannot support a requirement the product team considers obvious. These are not bugs; they are structural problems that often cannot be fixed without significant rework. Finding them in a document is orders of magnitude cheaper than finding them in production.

For documenting decisions that emerge from design review, see Architecture Decisions. For patterns to consider during design, see Scalability Patterns.

Why It Matters

Architectural problems found post-implementation are the most expensive kind. A missing field in a data model is a migration. A missing field discovered after the migration ran in production is a multi-week rollback plan, a data correction, and an incident report. The cost of a finding scales with how late in the process it is made. Design review moves findings as early as possible.

Alignment before effort prevents wasted work. The most expensive argument in engineering is the one that happens after a team has spent six weeks implementing a design that another team considers fundamentally wrong. Design review surfaces disagreements when they are still cheap to resolve — before anyone has invested in building anything.

Design review distributes architectural knowledge. Without review, system design is private knowledge held by the engineer who built something. Reviewers learn what is being built in areas they don't own, ask questions that surface unstated assumptions, and carry that knowledge into their own future decisions. This cross-pollination is one of the most durable ways a team raises its collective design ability.

The pre-mortem finds what proximity hides. An engineer deep in a design problem develops blind spots. They stop seeing the failure modes that seemed obvious before they got close to the problem. Reviewers, coming in fresh, often see exactly those things. A structured pre-mortem — asking "if this fails, why?" — surfaces the risks that are invisible to the author.

Standards & Best Practices

When to write a design doc

Design review is not free. A full design doc and review cycle takes time, and that cost must be justified by the risk of getting the design wrong. Write a design doc when:

• The change introduces a new service, data store, or external dependency
• The change defines an interface consumed by another team
• The change significantly modifies an existing data model
• The implementation will take more than one sprint
• The approach is genuinely uncertain — more than one reasonable design exists and the choice matters
• The change carries meaningful rollback complexity

Do not write a design doc for:

• Features that are implementation-only within an established pattern
• Changes that are entirely internal to one module with no interface changes
• Work where there is only one reasonable approach and the team agrees on it

Design doc structure

A design doc has a specific job: give reviewers enough context to evaluate trade-offs and flag problems. It is not a technical specification — it does not describe every implementation detail. It is not a project plan — it does not include timelines or ownership matrices. The goal is clarity about what is being built, why, and what the key design choices are.

Required sections:

• Problem — What are we solving? Who is affected? What happens if we do nothing?
• Goals and non-goals — Explicit scope. Non-goals are as important as goals — they prevent scope creep in review and signal what the author is not trying to solve.
• Proposed design — How it works. Data model changes, API contracts, sequence diagrams if helpful. Keep this as concise as possible while remaining unambiguous.
• Alternatives considered — What other approaches were evaluated, and why they were rejected. A doc with no alternatives considered signals that the author did not examine the design space.
• Trade-offs — What gets harder, more expensive, or riskier. A design doc with no trade-offs is not a design doc; it is a proposal waiting to be approved without scrutiny.
• Rollout plan — How this gets deployed. Migration steps, feature flags, backward compatibility.
• Open questions — Specific, answerable questions the author needs resolved before or during review.

Review before the build, not during it

The design review should be complete — reviewers should have given their feedback and the design should be approved — before implementation begins. A design review that runs concurrently with implementation provides the least useful feedback at the most disruptive moment.

The practical sequence:

1. Author writes the design doc
2. Author shares with reviewers, setting a deadline for feedback (typically 3–5 business days)
3. Reviewers comment asynchronously
4. Author addresses comments; escalates blockers to a synchronous discussion if needed
5. Design is approved; implementation begins

Async first, synchronous for blockers only

Most design feedback can be given and received asynchronously. A design review meeting where five engineers read a doc in real time is expensive and not substantially better than async review. Hold a synchronous session only when there is a genuine blocking disagreement that needs to be resolved in conversation.

When you do meet synchronously, come with a specific question or decision to make — not an agenda of "discuss the design." The meeting ends when the question is answered.

The pre-mortem technique

After completing a draft design, run a pre-mortem: ask "If this fails 12 months from now, what went wrong?" Write down every plausible failure. Group them by root cause. Then evaluate whether the design addresses those failures.

Pre-mortems are effective because they give reviewers explicit permission to be pessimistic. In normal design review, social pressure often suppresses concerns. A pre-mortem makes concern-raising the explicit goal.

Common pre-mortem findings in system design:

• "The service is a single point of failure with no fallback"
• "The data migration has no rollback path"
• "The third-party API has no SLA and we have no circuit breaker"
• "The caching layer becomes stale during peak hours and we have no invalidation mechanism"

Name trade-offs explicitly

Every design accepts trade-offs. A design that does not name them has hidden them — and hidden trade-offs surface at the worst moments. The trade-offs section of a design doc should include:

• What becomes more operationally complex
• What gets slower, more expensive, or more constrained
• What the system cannot do well after this design is in place
• What could be changed later, and what would be hard to reverse

Naming trade-offs is not a sign of a weak design. It is a sign that the author thought carefully about the design space and is being honest about the costs of their choice.

Distinguish review from approval

Design review is not a consensus mechanism. The goal is to surface information the author may not have, not to achieve unanimous agreement on every choice. The author is responsible for incorporating feedback, resolving open questions, and making a final decision. Reviewers advise; the author decides.

If review generates fundamental disagreement that cannot be resolved by the author, escalate to the relevant engineering lead or architect — but set a decision deadline. Unresolved design debates have a way of becoming multi-week process failures.

How to Implement

Reviewer checklist

When reviewing a design doc, evaluate it across these dimensions in order (coarser before finer):

1. Correctness — Does this design actually solve the stated problem? Are there scenarios where it fails?
2. Scope alignment — Does the design match the stated goals and non-goals? Is it solving more (or less) than intended?
3. Scalability — Under what conditions does this design break? Is that condition realistic in the next 12–24 months?
4. Operability — How do you debug this at 2am? What observability is built in? What does failure look like, and how do you recover?
5. Security surface — What new attack surfaces does this introduce? What data is now in motion or at rest that wasn't before?
6. Interface contracts — If this defines an API or event schema consumed by other teams, is it stable? Can it evolve without breaking consumers?
7. Rollback — If this goes wrong, how do you undo it? Is that plan practical?
8. Alternatives — Were the right alternatives considered? Was the chosen approach selected for the right reasons?

Decision doc (lighter weight than a full design doc)

For decisions that are too significant for an ADR but too small for a full design doc, a one-page decision doc is appropriate:

# Decision: [Short title]

**Status:** Proposed | Decided

**Decision by:** YYYY-MM-DD

---

## Context

[What situation requires a decision? 2–4 sentences.]

## Options

**Option A — [Name]**
[Description. Key advantages. Key disadvantages.]

**Option B — [Name]**
[Description. Key advantages. Key disadvantages.]

## Decision

[What we're doing and why. What trade-offs we accept.]

## Open questions

- [ ] [Anything still to resolve]

Review turnaround expectations

Tools & Templates

Full design doc template

# [Feature or System Name] — Design Doc

**Status:** Draft | In Review | Approved | Implemented

**Authors:** [Name(s)]

**Reviewers:** [Name(s)]

**Feedback deadline:** YYYY-MM-DD

---

## Problem

[What are we solving? Who is affected? What is the cost of doing nothing?]

## Goals

- [Specific, observable outcome this design achieves]

## Non-goals

- [What this design explicitly does not address — be as specific as the goals]

## Proposed Design

[How it works. Data model. API contracts. Sequence of operations.
Include diagrams where they reduce ambiguity.
Aim for the minimum description that is unambiguous.]

## Alternatives Considered

### [Alternative name]

[What it is. Why it was ruled out.]

## Trade-offs

**What gets easier:**

- [Concrete improvements]

**What gets harder or more expensive:**

- [Concrete costs]

**What we cannot easily change later:**

- [Lock-in decisions]

## Rollout Plan

[Deployment steps. Feature flags. Migration plan. Backward compatibility.]

## Observability

[What metrics, logs, and alerts will be added? How will you know this is
working correctly in production?]

## Open Questions

- [ ] [Specific question — who is responsible for answering it?]

Pre-mortem facilitation guide

Run asynchronously in a shared document, or synchronously in 30 minutes:

1. Share the design with participants 24 hours in advance
2. Each participant independently writes their top 3 "if this fails, why?" scenarios
3. Compile all scenarios; group by theme
4. For each theme: is it addressed in the current design? If not, should it be?
5. Update the design's trade-offs section with the outcomes

Common Pitfalls

Design review as a formality. Sharing a doc, getting one "+1" without real commentary, and marking it reviewed. The value of design review comes from genuine scrutiny. If reviewers are not asking questions or raising concerns, either the design is unusually obvious or the review process is not working.

The design doc that describes implementation, not design. A 15-page doc describing every class and method is not a design doc; it is a specification. Design docs should describe the key structural choices — the decisions that matter — not every detail of the implementation. Too much detail obscures the choices that actually need review.

Ignoring operability. Designs that work correctly under happy-path conditions but produce opaque failures under real conditions are common. Reviewers should specifically ask: how do you debug this at 2am? What does failure look like? How do you recover? A design with no answer to these questions is not production-ready regardless of its functional correctness.

Design by committee. A review process where every reviewer has veto power and disagreements are never resolved. Reviews should produce a decision, not a consensus. If design review consistently results in extended debate without resolution, the process needs a clearer decision-making mechanism and someone with authority to make the final call.

The review that happens after implementation. A design doc written to document what was already built is archaeology, not review. It has no ability to prevent problems — only to record them. If implementation has begun, a design review can still be useful for documenting the design and surfacing changes that could be made incrementally, but it cannot recapture the cheapest moment to catch problems.

Non-goals that are actually goals. Listing something as a non-goal to avoid the work of designing for it, when stakeholders actually expect it. Non-goals should be things the team has explicitly agreed are out of scope — not things the author hopes nobody will ask about. A non-goal that surprises reviewers needs to be negotiated, not asserted.