Skip to main content

Design Review Workshop

Play both reviewer and reviewee on the same design. The goal is to internalize both sides; many senior engineers are strong at one and blind to the other.

Budget: 2 focused sessions of ~90 minutes each.

Retrieval Prompts​

  1. State the six parts of the architectural storytelling arc (Concept 12).
  2. What is the difference between curiosity ("why did you...?") and judgment ("this is wrong") in a review?
  3. What must come out of a design review, in writing, before it ends?
  4. Name one warning sign that a reviewer is operating at the wrong altitude for the design under review.
  5. What is the minimum stakeholder-map content a design doc should carry?

Pick a Design​

Choose one of:

  • A. A recent design doc you wrote that was approved quickly. Revisit it with fresh eyes as a reviewer.
  • B. A design doc from a teammate - with permission - for structured critique.
  • C. A public design artifact (any open-source RFC, a published architecture case study, or a major company's engineering blog post that documents a concrete system).
  • D. Design a small system yourself for this workshop: 1-page proposal for a cache layer, a background job system, or an event bus. Under 200 words.

Part 1: Play the Reviewee​

Produce a design doc that uses the six-part architectural-storytelling arc:

  1. Problem (1-2 sentences; concrete).
  2. Constraint (1-2 sentences; what ruled out the easy answer).
  3. Options (3 alternatives, each in 2-3 sentences; state fairly, no strawmen).
  4. Choice (1 paragraph; one guiding principle + why).
  5. Consequences (2 paragraphs; at least one negative).
  6. Open questions (3 bullets; honestly).

Include a short stakeholder map at the top: who is Accountable, who is Consulted, who is Informed.

Before circulating, write your own pre-review checklist:

  • Can the reader name the problem in one sentence after reading only the first paragraph?
  • Are the alternatives fairly stated (no strawmen)?
  • Is there at least one negative consequence named?
  • Is the decision section or choice clearly marked?
  • Are there 2-3 open questions I am not asking reviewers to resolve yet?

Part 2: Play the Reviewer​

Switch to reviewer mode. Run this structured review on either your own doc (with a 24-hour cooling-off period) or a teammate's.

Review pass 1: Curiosity​

For each of the six story slots, ask one curiosity question - never judgment. Examples:

  • Problem: "What made this problem show up now and not six months ago?"
  • Constraint: "Was there a constraint that ruled out the obvious option?"
  • Options: "Can you name one option you considered and rejected that is not on this page?"
  • Choice: "What guiding principle made Option 2 the right one?"
  • Consequences: "What breaks first if this choice turns out wrong?"
  • Open questions: "Which of the open questions would change the design if answered differently?"

Good curiosity questions invite the author to strengthen their design. Bad ones are sneaky judgments.

Review pass 2: Judgment​

Only after the curiosity pass: name specific concerns. Each concern must be in SBI-like form:

  • Situation: which section of the doc.
  • Behavior: what specifically the doc says or omits.
  • Impact: what will go wrong if this ships as-is.

Aim for at most 5 judgments. More than 5 and the author cannot act on them all.

Review pass 3: Decision​

The review ends with a written decision section in the doc, not verbally. Options:

  • Accepted. Ship.
  • Accepted with changes. List the 1-3 required changes before merge.
  • Revise and resubmit. The doc is not yet ready. Name the specific sections.
  • Rejected. With written reason tying back to a specific concern.

Compare and Distinguish​

  • Curiosity vs judgment. Curiosity asks a question; judgment makes a claim. Both belong, in that order.
  • Concern vs blocker. A concern is a worry. A blocker is something that must be resolved before merge. Mark each judgment as one or the other.
  • Decision section vs "LGTM". A decision section names the outcome and the required changes. "LGTM" is not a decision section.
  • Author defense vs author clarification. Clarifying is adding information the reviewer lacked. Defending is arguing the reviewer is wrong before they have finished explaining.

Common Mistake Check​

In each excerpt, identify the review anti-pattern:

  1. "This won't scale." (judgment with no behavior or impact)
  2. "Why not just use Kafka?" (disguised judgment posing as curiosity)
  3. "LGTM, looks great overall, let's ship." (no decision section; no actions)
  4. "I have 37 comments." (reviewer load pushed to author; no prioritization)
  5. "Can we discuss this in a meeting?" (review escalated to synchronous without written preparation)

Evidence Check​

This workshop is complete when you can:

  • produce a design doc using the six-part arc in under 90 minutes
  • review a peer's doc with a curiosity pass, a judgment pass, and a decision section
  • identify at least one curiosity question you asked that surfaced a real issue the author had not written down
  • name one judgment you withheld because it was at a different altitude than the decision on the page