Skip to main content

Preparing a Review: Package, Agenda, Participants

What This Concept Is​

A review is shaped before it starts. Three ingredients decide whether it will produce a decision or a second meeting:

  • Package. What reviewers read in advance. Draft ADR, one or two diagrams, relevant constraints, the question(s) the review must answer.
  • Agenda. A time-boxed list of questions, not topics. "Is the two-way-door classification correct?" beats "Discuss reversibility."
  • Participants. The smallest set of people who together have the authority to decide. Anyone further is a cc, not a required attendee.

A review with a package but no agenda becomes a reading group. One with participants but no package becomes a guessing game. All three have to exist.

Why It Matters Here​

Review cost compounds. Ten people at a one-hour unprepared review is ten person-hours to produce nothing durable. The same ten hours split as one hour of preparation plus a focused 30-minute meeting with three required attendees produces an ADR.

Preparation is also a filter. Any proposal that cannot be summarized into a reviewable package is probably not ready for review.

Concrete Example​

Subject: Review: ADR-0044 - Event bus transport choice

Pre-read (10 min):

  • draft ADR-0044 (Nygard, 1 page)
  • context diagram: current + proposed
  • one-page summary of the cost model

Participants (required to decide):

  • author (platform team)
  • on-call lead from orders service (affected consumer)
  • ops lead (operational burden)

Optional (cc only):

  • analytics lead
  • security reviewer (signed off async, absent)

Agenda (45 min):

  1. (5 min) Author states the problem in their own words. No slides.
  2. (10 min) Reviewers ask clarifying questions, no evaluation yet.
  3. (15 min) Walk the three concrete scenarios in the ADR. Disagreements are captured in writing as we go.
  4. (10 min) Decide: accept, reject, or defer with specific followups.
  5. (5 min) Author updates the ADR live; the group reads what was written before ending.

Expected output: an ADR in Accepted status, or a dated followup list with owners.

Common Confusion / Misconception​

"Send a long pre-read to set context." A pre-read over 10 minutes will not be read. A short pre-read will. Write to the length that will actually be consumed.

"Everyone affected should attend." Affected is not the same as decision-necessary. Wide attendance dilutes accountability. Use explicit "required / optional / cc" labels.

"No agenda - let's see where it goes." Where it goes is nowhere. An agenda is one page; writing it is 10 minutes; it saves multiples of that in the room.

"ADR bureaucracy." Preparation is not bureaucracy. Bureaucracy is holding a review where nothing gets decided and no artifact is produced. Preparation is the thing that prevents that.

How To Use It​

As the author:

  1. Draft the ADR to load-bearing state first. If Consequences is empty, you are not ready.
  2. Reduce the pre-read to one page plus at most two diagrams.
  3. Pick the smallest decision-necessary participant set. Label everyone else cc.
  4. Write the agenda as 3-5 questions.
  5. Send the package at least 24 hours before the meeting. If that is impossible, postpone the meeting.

As a facilitator (may or may not be the author):

  1. Confirm the question the review must answer. If participants disagree on the question, stop and fix that first.
  2. Hold time for each agenda item. Capture disagreements as they happen.
  3. End with the ADR updated, not with a promise to update it later.

Check Yourself​

  1. What is the minimum package for a review? What can you drop without harm? What can you not?
  2. Why does "discuss" beat "decide" as an agenda verb approximately zero percent of the time?
  3. Name one stakeholder who should almost always be cc and not required for an architecture review, and defend it.

Mini Drill or Application​

For an upcoming review, prepare:

  • a one-page pre-read (the draft ADR plus context)
  • an explicit participant list with required / optional / cc labels
  • an agenda of 3-5 questions with time boxes
  • an expected output statement ("at the end of this meeting, the ADR will be Accepted or Rejected")

Send it. Note who actually reads the pre-read versus who shows up cold. This is data for calibrating future reviews.

Read This Only If Stuck​