Skip to main content

Mock Architecture Review

Kata: Run a mock lightweight review on a peer's ADR. You will play both the author and the reviewer in consecutive sessions. The goal is to experience both sides of the process and to produce the three required outputs: decision, followups, captured risks.

Retrieval Prompts​

  1. State from memory the three outputs a review must produce.
  2. What is the difference between the curiosity round and the judgment round?
  3. Why is "everyone affected should attend" a bad rule for a review?
  4. What must be included in a review package, at minimum?
  5. What makes a "defer" decision valid versus suspect?

Compare and Distinguish​

  • Async review vs sync meeting. When is each appropriate? What do they produce differently?
  • Required vs optional vs cc. Why does the distinction matter for review quality?
  • Curiosity vs judgment contributions. How do you tell when a "question" is actually a position?
  • Decision vs followup. What belongs in each, and where do they live?

Common Mistake Check​

Identify the failure mode each excerpt reveals:

  1. A review meeting ends with "let's talk about this more next week." (no decision output)
  2. A PR comment reads "LGTM." (rubber stamp; no substantive engagement)
  3. An agenda reads "Discuss auth architecture." (topic, not a question)
  4. A reviewer only ever asks: "Wouldn't it be better to just X?" (judgment dressed as curiosity)
  5. Participants list: the author, the VP of engineering, 8 cc'd stakeholders. (wrong decision-necessary set)

Mini Application​

Session A: Author.

  1. Write a draft ADR on a real architectural decision you could make today. Use MADR.
  2. Prepare a review package: draft ADR + at most two diagrams + one-page pre-read note.
  3. Write an explicit participant list: required, optional, cc.
  4. Write a 3-5 question agenda with time boxes.
  5. Run the review (real teammates, study group, or fictional proxies). Capture decision, followups, captured risks live.

Session B: Reviewer.

Take a peer's ADR (or a public one). In writing, provide:

  • 2 curiosity questions on Context
  • 1 question challenging a claim in Decision
  • 1 proposed alternative not listed by the author
  • 1 explicit judgment statement (in favor, against, or indifferent) with reasoning
  • 1 substantive comment on Consequences - especially probing for missing negatives

Critique and Rewrite​

Write a post-mortem of your own review session. Answer:

  • Did the curiosity round happen before the judgment round, or did they blur?
  • Did the ADR change during the review? By how much?
  • Were all three outputs (decision, followups, captured risks) written before the meeting ended?
  • Which of the author's claims was most effectively challenged?
  • What would you do differently next time?

Evidence Check​

This page is complete only when you can:

  • prepare a review package a peer would call "ready for review" without further prompting
  • run a 30-60 minute review that ends with an ADR in Accepted or Rejected status
  • produce followups with owners and dates before the meeting ends
  • list captured risks explicitly and route them to the right tracker
  • take both roles (author, reviewer) without defaulting to rubber-stamping or defensive mode