Review Checklist

Context & Problem

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

Decision

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

Consequences

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

Implementation Plan

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

Verification

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

Options (MADR template)

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

Meta

• Not done: Status is set correctly (usually proposed for new ADRs)
• Not done: Date is set
• Not done: Decision-makers are listed
• Not done: Title is a verb phrase describing the decision (not the problem)
• Not done: 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