ADR Review Checklist

Use this checklist in Phase 3 to validate an ADR before finalizing. The goal: could a coding agent read this ADR and start implementing the decision immediately, without asking any clarifying questions?

Agent-Readiness Checks

Context & Problem

• A reader with no prior context can understand why this decision exists
• The trigger is clear (what changed, broke, or is about to break)
• No tribal knowledge is assumed — acronyms are defined, systems are named explicitly
• Links to relevant issues, PRs, or prior ADRs are included

Decision

• The decision is specific enough to act on (not "use a better approach" but "use X for Y")
• Scope is bounded — what's in AND what's out (non-goals)
• Constraints are explicit and measurable where possible (e.g., "< 200ms p95" not "fast enough")

Consequences

• Each consequence is concrete and actionable, not aspirational
• Follow-up tasks are identified (migrations, config changes, documentation, new tests)
• Risks are stated with mitigation strategies or acceptance rationale
• No consequence is a disguised restatement of the decision

Implementation Plan

• Affected files/directories are named explicitly (not "the database code" but "src/db/client.ts")
• Dependencies to add/remove are specified with version constraints
• Patterns to follow reference existing code (not abstract descriptions)
• Patterns to avoid are stated (what NOT to do)
• Configuration changes are listed (env vars, config files, feature flags)
• If replacing something, migration steps are described

Verification

• Criteria are checkboxes, not prose
• Each criterion is testable — an agent could write a test or run a command to check it
• Criteria cover both "it works" (functional) and "it's done right" (structural/architectural)
• No criterion is vague ("it performs well" → "p95 latency < 200ms under 100 concurrent requests")

Options (MADR template)

• At least two options were genuinely considered (not just "do the thing" vs "do nothing")
• Each option has real pros AND cons (not a straw-man comparison)
• The justification for the chosen option references specific drivers or tradeoffs
• Rejected options explain WHY they were rejected, not just what they are

Meta

• Status is set correctly (usually proposed for new ADRs)
• Date is set
• Decision-makers are listed
• Title is a verb phrase describing the decision (not the problem)
• Filename follows repo conventions

Quick Scoring

Count the checked items. This isn't a gate — it's a conversation tool.

• All checked: Ship it.
• 1–3 unchecked: Discuss the gaps with the human. Most can be fixed in a minute.
• 4+ unchecked: The ADR needs more work. Go back to Phase 1 for the fuzzy areas.

Common Failure Modes

Symptom	Root Cause	Fix
"Improve performance" as a consequence	Vague intent	Ask: "improve which metric, by how much, measured how?"
Only one option listed	Decision already made, ADR is post-hoc	Ask: "what did you reject and why?" — capture the reasoning
Context reads like a solution pitch	Skipped problem framing	Rewrite context as the problem, move solution to Decision
Consequences are all positive	Cherry-picking	Ask: "what gets harder? what's the maintenance cost?"
"We decided to use X" with no why	Missing justification	Ask: "why X over Y?" — the 'over Y' forces comparison
Implementation Plan says "update the code"	Too abstract	Ask: "which files, which functions, what pattern?"
Verification says "it works"	Not testable	Ask: "what command would you run to prove it works?"
No affected paths listed	Implementation Plan is hand-wavy	Agent should scan the codebase and propose specific paths