Decision Review
Review past decisions periodically to catch ones that are outdated, and to learn from ones that aged well or poorly.
Why
Decisions made 2 years ago may be wrong now — the vendor went EOL, the team's expertise changed, the scale outgrew the choice. Without periodic review, these stale decisions accumulate as technical debt that everyone complains about but no one re-examines. Decision review is the quarterly practice of reading the ADR log, flagging decisions whose context has changed, and either confirming or superseding them. It's also a learning exercise: comparing what we predicted (the Consequences section) vs what happened reveals which decision-makers are calibrated and which criteria are predictive. Teams that review their decisions get better at making them.
When
Quarterly, 2 hours. Skip only if the ADR log is < 10 decisions.
How
1. Read the ADR log (all accepted ADRs, oldest first) 2. For each, ask: has the context changed? - Vendor still viable? Team expertise still accurate? Scale still in range? 3. Flag decisions where context changed → candidate for supersession 4. For superseded candidates, write a new ADR that references the old + explains the change 5. For decisions that aged well, note what made them durable (calibration data) 6. For decisions that aged poorly, note what was missed (anti-calibration data) 7. Share the review summary with the team — the learning is the point
Example
Q3 ADR review (12 ADRs): ADR-003 (use Lambda for API): context changed — traffic grew 20x, Lambda now 5x cost → supersede by ADR-024 (move to Fargate), references ADR-003 ADR-007 (use Mongo for catalog): aged well — access patterns still fit, no issues → note: "document store for read-heavy catalog was durable" ADR-011 (use REST not gRPC): aged poorly — internal services now want typed RPC → supersede by ADR-025 (gRPC for internal, REST for external) Learning: cost-based decisions age poorly when scale changes; fit-based decisions age well. Share in retro.
Common Problems
- ⚠Reviewing but not superseding — the team agrees the decision is stale but no one writes the new ADR, so the stale one stays 'accepted'; supersede or it's not a review.
Best Practices
- ✓Time-box the review to 2 hours — longer and it becomes a re-litigation of every decision; flag and move on.
- ✓Track the calibration data over time — 'decisions based on cost were wrong 60% of the time' is a meta-learning that improves future decisions.