Cheat Sheet: Design Review

🎧Listen to this page5:08

Read the transcript

1. When to use it, and the order that makes a review worth an hour

Host: So today’s cheat sheet is Design Review, and I want to be really clear upfront about which side of the table we’re sitting on. This isn’t about how to present your own design well — that’s a different sheet, Design Round, go find that one if that’s your problem this week. Today we’re the ones with the document in front of us and an hour on the calendar, and we have to figure out where to spend that hour.

Guest: Right, and that framing matters more than people think, because reviewing well is a completely different skill from designing well. The sequence we’re walking through today exists specifically to stop you from reacting on gut instinct, because gut-reaction review wastes the hour on cheap comments and misses the expensive ones.

Host: Give me the shape of that sequence, then, before we dig into each piece.

Guest: It’s seven steps, and the order is the whole point. You start by reading constraints before the diagram — if they’re missing or just adjectives, that’s already your finding, stop there. Then you check the requirements actually shape the design, find the single hardest-to-reverse decision since that’s where most of the value concentrates, trace one request end to end to catch the seams nobody described, demand a falsifiable claim for anything like ‘it will scale,’ cover cost and observability last but always since those sections go missing constantly, and finally separate blocking from non-blocking comments explicitly in writing, because mixed together they get treated as either all-optional or all-mandatory.

2. The tools: questions that find real problems, and how to spend attention

Host: Okay, walk me through the actual questions, section by section, because ‘check the constraints’ is still pretty vague to someone staring at a doc.

Guest: Sure — for constraints you’re asking peak rps, the p99 target, what ‘correct’ even means here, whose data it is, and cost per call. For capacity, does arrival rate times latency actually agree with the pool size and replica count they configured, or did someone just pick round numbers. State is about who owns it, what a failure loses, and what happens the moment there’s a second replica. Retries need bounded attempts, a bounded total deadline, jitter, and an idempotent handler — miss any one of those and retries become the outage. Failure asks what breaks first at ten times load and what the blast radius is if something’s fully compromised. Data is one sharp question: is permission filtering inside the query or bolted on after retrieval, because that’s a leak waiting to happen. Quality asks if there’s an eval set with a threshold and an owner, or just a latency dashboard pretending to be quality monitoring. And rollout asks if it’s reversible in one deploy, and if not, what evidence would actually change the decision.

Host: That’s a lot of ground — so how do you triage where to actually spend your limited attention across all that?

Guest: That’s the reversibility sort: config change first, since that’s minutes to undo; component swap next, that’s roughly a week of pain; data model or tenant boundary changes last, because those aren’t a redo, they’re a migration, an audit, maybe a disclosure. Spend your attention in that order, not the order the document happens to present things. And once you’ve found something worth flagging, make the comment land — name the constraint you’re reasoning from, state concretely what you predict will fail, and say what evidence would change your mind. A comment with all three parts is hard to wave away and easy to actually act on, which is the whole point of doing the review in the first place.

3. Red flags — in the design, and in your own reviewing

Host: Before we wrap, give me the smell test — what tells you a design is in trouble before you’ve even done the reversibility sort? And is there a mirror version of that for the reviewer, ways we sabotage our own review?

Guest: On the design side: technologies picked before the constraints were written down, capacity described in adjectives like ‘fast’ or ‘scalable’ instead of numbers, the model treated as a black box that just returns a string with no evaluation story attached, security that only ever means authentication, and any decision with no stated cost — those are the tells. On the reviewing side, watch yourself for rewriting the design into the one you’d have built, which isn’t a review, it’s a competing draft; for litigating a two-way door that’s cheap to reverse and not even your code to own; for comments with no constraint behind them, which just read as taste and get dismissed as taste; for approving because the prose was clean, since writing quality and design quality don’t correlate at all; and for blocking on something without saying how you’d fix it or how you’d know it was fixed, which just stalls the thing instead of improving it. Catch those five and five, and the review does what it’s for — it moves the design forward instead of just performing scrutiny on it.

Not covered

The planner wanted these and found nothing in the source to support them:

• How to structure the review meeting itself (agenda, who speaks when) beyond the written sequence
• How a design review’s findings get converted into an ADR or other permanent record
• Team-specific customization of the checklist for different system types (e.g., RAG vs gateway) — the cheat sheet gives generic questions only

Generated from this page by Claude Sonnet 5 on 2026-08-23, spoken by Kokoro-82M running locally. Two synthetic voices, not a recorded conversation. Every claim is drawn from this page — where it differs from the text above, the text is correct.

Use This When

Someone has sent you a design document and you have an hour. This is the reviewing side, not the producing side — for the round where you present, use Design Round.

Depth lives in Module 13 and Module 14. The Architecture pages are worked examples of what a design that survives review contains.

The Sequence

1. Read the constraints before the diagram. If they are missing or written as adjectives, stop there — every downstream comment is unanchored, and that is the finding.
2. Check that the requirements would change the design. If you could swap the volume or latency target and the architecture stayed identical, the constraints are decoration.
3. Find the decision that is hardest to reverse. Data boundary, state ownership, external contract. Ask whether the author knows which one it is — most review value concentrates here.
4. Trace one request end to end and look for the seam nobody described: retries, partial failure, what holds state, what happens on redeploy.
5. Ask what would refute it. Each claim needs a measurement and a threshold. “It will scale” is not reviewable.
6. Comment on cost and observability last but always. They are the two sections most often missing and the two that predict operability.
7. Separate blocking from non-blocking, explicitly, in writing. Reviews that mix them get treated as all-optional or all-mandatory, and both are wrong.

Quick Reference

Questions that find real problems

Section	Ask
Constraints	Peak rps, p99 target, what “correct” means, whose data, cost per call
Capacity	Does arrival_rate × latency agree with the configured pool and replica counts?
State	Who owns it, what a failure loses, what happens on the second replica
Retries	Bounded attempts, bounded total deadline, jitter — and is the handler idempotent?
Failure	What breaks first at 10×? What is the blast radius of full compromise?
Data	Is permission filtering inside the query, or applied after retrieval?
Quality	Is there an eval set, a threshold, and an owner? Or only latency monitoring?
Rollout	Reversible in one deploy? If not, what evidence would change the decision?

Reversibility sort — config change (minutes) → component swap (a week) → data model or tenant boundary (a migration, an audit, a disclosure). Spend review attention in that order, not in the order the document is written.

Feedback that lands — name the constraint you are reasoning from, state the failure you predict concretely, and say what would change your mind. A comment with all three is hard to dismiss and easy to act on.

Red Flags

• In the design: technologies chosen before constraints · capacity in adjectives · the model treated as a function returning a string · no evaluation story · security discussed only as authentication · no stated cost for any decision.
• In your review: rewriting the design as the one you would have written — that is a different document, not a review.
• Litigating a two-way door. If it is reversible in a deploy and the author owns the code, let it go.
• Comments with no stated constraint behind them, which read as preference and get treated as such.
• Approving because it is well written. Prose quality and design quality are uncorrelated.
• Blocking on something you have not said how to fix, or how you would know it was fixed.