session · shaping
ADR / PDR review
30 minutes. Author plus at least one reviewer. The decision walks; the rejected options are read aloud; the trade-off is named. The session signs the decision from Proposed to Accepted — and nothing gets coded against a decision still in Proposed.
When
- When the ADR or PDR's author flags it for review — author marks Status: Proposed, posts the link, schedules.
- Within 48 hours of flagging — decisions in Proposed longer than that decay into shadow decisions.
Who
- Author — Tech Lead (for ADR), PO (for PDR).
- At least one reviewer — a peer Tech Lead for an ADR; a peer PO or trio member for a PDR.
- (For high-blast-radius decisions) a third reviewer — e.g., Designer if the decision affects flow; CS Lead if it affects support.
Time-box
30 minutes. Anything longer means the decision needs spike work, not review.
Inputs
- The ADR/PDR draft in Status: Proposed.
- The Feature Brief or Epic this decision constrains.
- Related ADRs/PDRs already accepted.
Agenda
| Time | What |
|---|---|
| 0–5 min | Read the title and the context aloud. "ADR-014: Idempotency keys for grading submissions. The context is..." The reviewer hears the framing before the options. |
| 5–15 min | Walk the options. Each — including do nothing — read aloud with one-line pros and cons. If the author cannot say do nothing's consequences clearly, that's the first finding. |
| 15–22 min | The trade-off. What is being chosen to lose? What is being deferred? Every real decision loses something. If the room cannot name what's lost, the decision is not yet a decision. |
| 22–27 min | Risks and consequences. "Where could this surface as a defect six weeks from now?" The reviewer walks the chain — could this miss surface at the integration layer? At the design layer? Could it produce adr-drift two cycles later? |
| 27–30 min | Sign. Status moves Proposed → Accepted. Author + reviewer signatures. Dated. |
Outputs
- Signed ADR or PDR with Status: Accepted.
- Linked from the Feature Brief or Epic it constrains.
- (Optional) spike or follow-up task if the review surfaced something incomplete.
What good looks like
The reviewer changes the decision in small ways — not the chosen option, usually, but the rationale, the trade-off naming, the risk list. That's the value of review. A reviewer who says "LGTM" and signs has not reviewed.
The do nothing option is treated as a real option. The author can describe what shipping the cycle without solving this looks like, what it would cost, who it would affect. That cost is the implicit price of choosing any of the active options.
Anti-pattern
The session becomes a presentation, not a review. The author talks for 25 minutes; the reviewer nods and signs. Fix: the reviewer asks one of the four questions: (1) Is the second option real? (2) What is being lost? (3) What is the do-nothing path? (4) Could this drift? If those don't surface a finding, the review has not happened.
A second anti-pattern: ADR/PDR stuck in Proposed indefinitely. The author waits for the "right" reviewer, weeks pass, code gets written against the unaccepted decision. Fix: if no reviewer is available in 48 hours, the author flags it as a chain-level signal at retro.
See also
- Canon — What We Build · ADR · Technical ADR · The PDR
- Template — ADR (MADR format)
- Areas — ADR · Product Decision Records
- Checklist — ADR · ≥2 options
- Clinic — An ADR with one option