ADR Review Process
A lightweight gate so ADRs get genuine technical scrutiny, not just rubber-stamp approval.
Why
An ADR that nobody reviewed is just one person's opinion checked into git. The value of an ADR comes from the collective stress-testing of the decision: did we consider the failure mode? does this conflict with an existing ADR? is the consequence acceptable to the on-call team? A defined review process catches decisions that are locally optimal but globally inconsistent. Without it, you get 40 ADRs that each look fine in isolation but contradict each other on, say, consistency models.
When
Every Proposed ADR before it becomes Accepted. Budget 30 min per review, 1-2 reviews per week. Skip only for trivial, fully reversible decisions.
How
1. Author sets Status=Proposed and requests review from 2 named reviewers: - One senior engineer outside the immediate team (cross-cutting view) - One on-call/ops representative (consequences fall on them) 2. Reviewers check in the PR comment: - Are the alternatives and rejection reasons real? - Does this conflict with any existing Accepted ADR? (grep docs/adr) - Are the negative consequences acknowledged and acceptable? 3. Author addresses comments; reviewers leave explicit "LGTM" comments 4. Author flips Status=Accepted after 2 approvals; merge the PR 5. Log the decision in the weekly architecture sync (1 line, link to ADR)
Example
ADR-0013 (Proposed): "Adopt Kafka for inter-service messaging" Reviewers: @diana (platform), @carlos (on-call) @diana: "Context doesn't mention ADR-0009 where we chose RabbitMQ. Why change? Also: who operates the Kafka cluster?" @carlos: "Negative consequences omit pager load — Kafka rebalances can stall consumers for 30s, that's an on-call incident." Author updates Context (links ADR-0009, explains throughput change), adds consequence "- on-call may see 30s consumer stalls during rebalance". Both LGTM → Accepted.
Common Problems
- ⚠Assigning the same two reviewers every time — they become a bottleneck and lose fresh perspective; rotate the cross-cutting reviewer quarterly.
- ⚠Reviewing only the Decision sentence and not the Consequences — the consequences are where ops pain lives, and skipping them guarantees future incidents.
Best Practices
- ✓Keep a running 'ADR conflicts' check in CI that greps for contradictory decisions (e.g. two ADRs picking different primary stores).
- ✓Time-box reviews to 30 min; if it needs more, the decision is too big for one ADR and should be decomposed.
- ✓Publish accepted ADRs to an internal wiki page so non-engineers (product, security) can see the architecture rationale.