Adr

Architecture Decision Records

Expert guidance for creating and managing Architecture Decision Records based on Olaf Zimmermann's research and the MADR (Markdown Architectural Decision Records) methodology.

How This Skill Works

When invoked, this skill guides you through the full ADR lifecycle:

1. Readiness assessment — Evaluate whether a decision is ready to be recorded (START criteria) 2. Creation — Write well-structured ADRs using the MADR template with anti-pattern avoidance 3. Quality evaluation — Check completeness using the ECADR "Definition of Done" criteria 4. Lifecycle management — Maintain ADR logs, supersede outdated records, track decision status

Core Philosophy

"Don't decide too early, this harms flexibility. Don't decide too late either."

ADRs function as decision journals — not blueprints or policies. They capture the rationale behind architecturally significant choices: the problem context, the alternatives considered, the criteria applied, and the consequences accepted. Good ADRs are executive summaries that balance tradeoffs, not sales pitches for a predetermined outcome.

When to Use This Skill

• Creating a new ADR for an architectural decision
• Evaluating whether a decision is ready to be recorded
• Reviewing an existing ADR for completeness and quality
• Writing or customizing a MADR template for a project
• Assessing whether a requirement is architecturally significant
• Managing an ADR log (superseding, deprecating, linking decisions)
• Training teams on ADR best practices

Command Modes

The MADR Template (Quick Reference)

# ADR-NNNN: [Short Title Describing Decision]

## Status
[proposed | accepted | deprecated | superseded by ADR-XXXX]

## Date
YYYY-MM-DD

## Decision Makers
[Who made or approved this decision]

## Context and Problem Statement
[1-3 paragraphs: What is the issue? Why does it matter?
Frame as a question when possible.]

## Decision Drivers
- [Driver 1: quality attribute, business constraint, or technical concern]
- [Driver 2]
- [Driver 3]

## Considered Options
1. [Option A — the chosen option]
2. [Option B]
3. [Option C]

## Decision Outcome
Chosen option: "[Option A]", because [justification referencing decision drivers].

### Consequences
- Good, because [positive consequence]
- Good, because [another benefit]
- Bad, because [accepted tradeoff]
- Bad, because [known limitation]

## Pros and Cons of Options

### Option A
- Good, because [advantage]
- Bad, because [disadvantage]

### Option B
- Good, because [advantage]
- Bad, because [disadvantage]

### Option C
- Good, because [advantage]
- Bad, because [disadvantage]

## Validation
[How will we verify this decision works? Code review, design review,
architectural fitness function, spike, etc.]

## More Information
[Links to related ADRs, RFCs, spikes, or external references.
Note confidence level and planned review date.]

Key Frameworks

START — Definition of Ready

Before writing an ADR, confirm all five criteria:

• Stakeholders known and available
• Timing is the Most Responsible Moment
• Alternatives identified (minimum two)
• Requirements and context documented
• Template selected and instantiated

ECADR — Definition of Done

Before marking an ADR as accepted, confirm all five criteria:

• Evidence that the design will work
• Criteria applied to compare at least two alternatives
• Agreement from relevant stakeholders
• Documentation captured and shared
• Realization and review plan scheduled

ASR Test — Architectural Significance

A requirement warrants an ADR when it scores on these criteria:

• High business impact or risk
• Critical stakeholder concern
• Quality-of-service deviation from current architecture
• External dependency that is unpredictable or uncontrollable
• Cross-cutting concern affecting multiple components
• First-of-a-kind implementation for the team
• Historical precedent of causing problems

What This Skill Provides

1. Readiness assessment using START criteria with checklists 2. MADR template generation (full and minimal variants) 3. Anti-pattern detection in draft ADRs (11 known anti-patterns) 4. Quality evaluation using ECADR Definition of Done 5. Architectural significance assessment for prioritizing decisions 6. Lifecycle guidance for maintaining ADR logs over time

ADR Rules

Sections

Readiness

Evaluating when a decision is ready to be recorded.

• readiness-start-criteria.md - The START criteria for decision readiness
• readiness-architectural-significance.md - Assessing if a decision warrants an ADR

Creation

Writing high-quality ADRs.

• creation-madr-template.md - The MADR template structure and guidance
• creation-writing-principles.md - Seven good practices for ADR authorship
• creation-anti-patterns.md - Eleven anti-patterns to avoid in ADRs

Completion

Evaluating ADR quality and completeness.

• completion-ecadr-criteria.md - The ECADR Definition of Done checklist
• completion-validation.md - Evidence gathering and stakeholder agreement

Lifecycle

Managing ADRs over time.

• lifecycle-management.md - ADR log maintenance, superseding, and review cycles

ECADR Definition of Done

Impact: CRITICAL

Before marking an ADR as "accepted", evaluate all five ECADR criteria. An incomplete ADR creates false confidence — the team thinks a decision was properly made, but gaps in evidence or agreement lead to revisiting it later under worse conditions.

The Five Criteria

E — Evidence Confirm the chosen design will work:

• Demonstrates it satisfies specific, measurable quality requirements
• Doesn't contradict previous accepted decisions
• Implementable in the short term and maintainable long-term

Validation methods (pick what fits):

• Proof-of-concept or architectural spike
• Expert evaluation or vouching
• Team review with relevant experience
• Reference to similar production systems

C — Criteria At least two alternatives have been identified, investigated, and compared using stakeholder concerns and decision drivers:

• Systematic comparison applied (but pragmatically — avoid over-analysis)
• Tradeoffs between options documented
• Rejected alternatives retained as noted fallbacks where applicable

A — Agreement Sufficient stakeholder alignment achieved:

• Peer/mentor and team have reviewed and concurred
• Involvement level matches decision scope (enterprise decisions need more buy-in)
• Early engagement of stakeholders to prevent later objections
• Stakeholder participation planned in advance, not an afterthought

D — Documentation The decision has been captured and shared:

• Written in MADR or the team's consistent ADR format
• Includes convincing rationale referencing evidence and criteria
• Published in an accessible location (repo, wiki, collaboration tool)
• Announced to all affected parties

R — Realization and Review Plan Implementation and evaluation are scheduled:

• Confirm implementation work is in the backlog or scheduled
• Define when to verify the decision worked as intended
• Plan review timing (sprint retrospective, ATAM session, quarterly review)
• Document triggers for revisiting the decision (assumptions that could change)

Quick Completion Check

Answer "yes" to all five questions:

1. Is there sufficient confidence the design will work? (Evidence) 2. Were at least two options compared systematically? (Criteria) 3. Have relevant stakeholders reviewed and aligned? (Agreement) 4. Has the decision been documented and shared? (Documentation) 5. Are implementation and review tasks scheduled? (Realization)

If any answer is "no", either complete that criterion or document why it doesn't apply before proceeding.

Good Example

## Completion Check: ADR-0012 PostgreSQL for User Service

- [x] **Evidence**: Spike in ADR-0011 demonstrated <8ms p99 reads with
      production-like data volume (2M rows). No conflicts with existing
      ADRs (checked ADR-0003, ADR-0007).
- [x] **Criteria**: PostgreSQL, DynamoDB, and CockroachDB compared across
      latency, consistency, operational familiarity, and cost.
- [x] **Agreement**: Backend team reviewed in sprint planning. SRE team
      confirmed operational readiness. Product approved timeline impact.
- [x] **Documentation**: ADR-0012 published in docs/decisions/, announced
      in #architecture Slack channel.
- [x] **Realization**: Migration ticket PROJ-456 created in sprint 14.
      Review scheduled for sprint 18 retrospective. Revisit triggers:
      if write throughput exceeds 10K/sec or if we expand beyond 2 regions.

✅ ADR-0012 is done. Status changed to "accepted".

Scaling Effort to Impact

Checklist

• [ ] Evidence exists that the chosen design satisfies requirements
• [ ] At least two alternatives were compared using documented criteria
• [ ] Relevant stakeholders have reviewed and agreed
• [ ] ADR is written, published, and announced to affected parties
• [ ] Implementation work is scheduled and review triggers are defined

Evidence Gathering and Stakeholder Agreement

Impact: MEDIUM-HIGH

The Evidence and Agreement criteria of ECADR deserve deeper guidance because they are the most commonly skipped steps. Teams often accept decisions without proving they work or confirming alignment.

Evidence Strategies

Choose the validation method appropriate to the decision's risk level:

What Good Evidence Looks Like

## Validation

### Spike Results (ADR-0011)
- Tested PostgreSQL read replicas with 2M row dataset
- Achieved 7.2ms p99 read latency (requirement: <10ms)
- Cross-region replication lag: 45-80ms (acceptable for read replicas)
- Failover tested: 12-second promotion time

### Operational Readiness
- Team has 4 years PostgreSQL production experience
- Existing monitoring (PgBouncer, pg_stat_statements) transfers directly
- Backup/restore runbook exists from User Service v1

### Known Gaps
- Write scaling beyond 10K/sec not tested (expected Year 2 requirement)
- Multi-region write not validated (would need CockroachDB if required)

What Bad Evidence Looks Like

## Validation
We're confident PostgreSQL will work because it's widely used.
The internet says it's good for this kind of workload.

This lacks specific measurements, team context, and honest gap analysis.

Stakeholder Agreement Patterns

For team-level decisions:

• Present in team standup or sprint planning
• Capture verbal agreement in the ADR ("Discussed in sprint 14 planning, team agreed unanimously")
• Allow 2-3 day review period for async teams

For cross-team decisions:

• Schedule a dedicated review session
• Send ADR draft to all affected teams with explicit review deadline
• Document dissenting opinions and how they were addressed
• Require explicit sign-off from team leads

For organization-level decisions:

• Architecture review board or technical leadership review
• Formal presentation with Q&A
• Written approval from designated authority
• Communication plan for rollout

Handling Disagreement

When stakeholders disagree, document it honestly:

## More Information

### Stakeholder Positions
- **Backend team**: Preferred PostgreSQL for operational familiarity
- **SRE team**: Preferred CockroachDB for built-in multi-region support
- **Resolution**: PostgreSQL chosen for Year 1 with explicit migration
  trigger (ADR-0012a) if multi-region writes become a requirement.
  SRE team's concern addressed by scheduling CockroachDB evaluation
  in Q3 if write scaling exceeds projections.

Checklist

• [ ] Validation method chosen appropriate to decision risk level
• [ ] Evidence includes specific measurements or concrete experience, not just opinions
• [ ] Known gaps and assumptions explicitly documented
• [ ] All affected stakeholders have reviewed (not just the author's team)
• [ ] Disagreements documented with resolution approach
• [ ] Agreement captured in the ADR record itself, not just verbal

Eleven ADR Anti-Patterns

Impact: HIGH

These anti-patterns are distilled from Olaf Zimmermann's research into common ADR failures. When reviewing or writing ADRs, check for these problems. They fall into four categories: subjectivity issues, time-dimension problems, structural issues, and deceptive tactics.

Subjectivity Issues

1. Fairy Tale Shallow justification that presents only benefits without acknowledging tradeoffs or drawbacks. Real engineering decisions always involve costs.

# Bad: Fairy Tale
## Consequences
- Good, because microservices are modern and scalable
- Good, because teams can deploy independently
- Good, because we can use the best tool for each job
# Where are the bad consequences?

2. Sales Pitch Marketing language, exaggerations, and unsubstantiated claims. ADRs are technical journals, not vendor brochures.

# Bad: Sales Pitch
"Kubernetes is the industry-leading, battle-tested, enterprise-grade
platform that will revolutionize our deployment pipeline."
# vs. Good: Factual
"Kubernetes provides container orchestration with automated scaling.
Our team has no production K8s experience, requiring 2-3 months ramp-up."

3. Free Lunch Coupon Ignoring difficult consequences, especially long-term operational costs, maintenance burden, and team skill requirements.

4. Dummy Alternative Including an obviously unworkable option to make the preferred solution look better. Every listed alternative must be a genuine candidate that could solve the stated problem.

# Bad: Dummy Alternative
## Considered Options
1. Use Redis for caching (our preferred approach)
2. Build a custom caching layer from scratch in assembly
3. Don't use caching at all
# Options 2 and 3 are clearly not real alternatives

Time-Dimension Problems

5. Sprint Considering only one option and only immediate effects. No comparison, no long-term thinking. This is a mandate disguised as a decision.

6. Tunnel Vision Ignoring operational, maintenance, and cross-stakeholder perspectives. A decision that's great for developers but terrible for SREs is not a good decision.

7. Maze Topic-content mismatch with irrelevant detail discussions. The ADR wanders into implementation specifics, tangential research, or unrelated concerns instead of staying focused on the decision.

Structural Issues

8. Blueprint or Policy in Disguise Cookbook-style documents with step-by-step instructions and commanding tone ("you must", "always do"). ADRs document decisions, not procedures.

9. Mega-ADR Stuffing extensive architectural details, multiple diagrams, code snippets, and exhaustive analysis into a single record. If an ADR exceeds 2-3 pages, it likely needs to be split or it's trying to be an architecture document.

10. Novel/Epic Condensing an entire Software Architecture Document into a single ADR. Each ADR should address one specific decision, not the entire system design.

Deceptive Tactics

11. Magic Tricks Pseudo-urgency, problem-solution mismatches, or false quantitative precision. This includes weighted scoring matrices without meaningful measurement — assigning numbers to subjective criteria to create an illusion of objectivity.

# Bad: Magic Tricks (false precision)
| Criteria    | Weight | Redis | Memcached | PostgreSQL |
|-------------|--------|-------|-----------|------------|
| Performance | 0.35   | 9     | 8         | 5          |
| Reliability | 0.25   | 8     | 6         | 9          |
| Total       |        | 8.65  | 7.10      | 6.60       |
# These numbers are subjective, but the scoring creates false objectivity

Detection Checklist

When reviewing an ADR, check for these red flags:

• [ ] No negative consequences listed → Fairy Tale
• [ ] Superlatives or marketing language → Sales Pitch
• [ ] Operational costs not mentioned → Free Lunch Coupon
• [ ] An option that nobody would seriously consider → Dummy Alternative
• [ ] Only one option evaluated → Sprint
• [ ] Only developer perspective considered → Tunnel Vision
• [ ] Rambling into unrelated topics → Maze
• [ ] Step-by-step instructions instead of rationale → Blueprint
• [ ] Exceeds 3 pages with extensive diagrams/code → Mega-ADR
• [ ] Covers multiple unrelated decisions → Novel/Epic
• [ ] Weighted scoring with subjective numbers → Magic Tricks

MADR Template Structure

Impact: CRITICAL

Use the Markdown Architectural Decision Record (MADR) template for all ADRs. Consistency across records makes the decision log searchable, reviewable, and maintainable. Every ADR should follow this structure, customizing optional sections as appropriate for the decision's complexity.

Full Template

# ADR-NNNN: [Short Noun Phrase Describing Decision]

## Status
[proposed | accepted | deprecated | superseded by ADR-XXXX]

## Date
YYYY-MM-DD

## Deciders
[Names and roles of decision makers]

## Consulted
[Subject matter experts with two-way communication]

## Informed
[Stakeholders receiving one-way updates after the decision]

## Context and Problem Statement
[1-3 paragraphs explaining the situation. Frame as a question when possible.
Include links to issue trackers, RFCs, or collaboration boards.
Make the reader curious about why this matters.]

## Decision Drivers
- [Quality attribute, business constraint, or technical concern]
- [Each driver should be a concrete, measurable concern when possible]
- [Drivers justify why the criteria matter]

## Considered Options
1. [Option A — list the chosen option first by convention]
2. [Option B]
3. [Option C]

## Decision Outcome
Chosen option: "[Option A]", because [justification referencing
the decision drivers above].

### Consequences
- Good, because [positive consequence for the system/team/users]
- Good, because [another benefit]
- Bad, because [accepted tradeoff or limitation]
- Bad, because [known cost or risk]

## Pros and Cons of Options

### Option A
[Brief description or link to more detail]
- Good, because [advantage]
- Good, because [another advantage]
- Bad, because [disadvantage]
- Neutral, because [neither good nor bad, but worth noting]

### Option B
[Brief description]
- Good, because [advantage]
- Bad, because [disadvantage]
- Bad, because [another disadvantage]

### Option C
[Brief description]
- Good, because [advantage]
- Bad, because [disadvantage]

## Validation
[How will compliance be verified? Code review, design review,
architectural fitness function, spike, load test, etc.]

## More Information
[Links to related ADRs, RFCs, spikes, or external references.
State confidence level and planned review date.
Note any assumptions that could invalidate this decision.]

Minimal Template (MADR Light)

For simpler or lower-impact decisions, use five core sections:

# ADR-NNNN: [Short Title]

## Context and Problem Statement
[Brief situation description]

## Decision Drivers
- [Key driver 1]
- [Key driver 2]

## Considered Options
1. [Option A]
2. [Option B]

## Decision Outcome
Chosen option: "[Option A]", because [justification].

### Consequences
- Good, because [benefit]
- Bad, because [tradeoff]

Section Guidance

Checklist

• [ ] Title is a short noun phrase that describes the decision (not the problem)
• [ ] Status is set (proposed for new, accepted after review)
• [ ] Context frames the problem clearly — a newcomer could understand it
• [ ] At least two decision drivers are listed
• [ ] At least two options are compared at consistent abstraction levels
• [ ] Outcome explicitly names the chosen option with justification
• [ ] Consequences include both positive and negative items
• [ ] Chosen option listed first in the Considered Options list

Seven Good Practices for ADR Authorship

Impact: HIGH

These principles distinguish useful ADRs from bureaucratic checkbox exercises. An ADR should read like an executive summary — factual, balanced, and actionable.

1. Prioritize by Architectural Significance

Focus ADR effort on decisions with meaningful consequences. Use the ASR test to triage. Not every technical choice needs a record — reserve ADRs for decisions that affect system structure, quality attributes, or cross-cutting concerns.

2. Capture Decisions at the Right Time

Don't defer high-impact decisions. Costly-to-reverse choices (database systems, programming languages, architectural styles) require immediate documentation. The cost of delay grows exponentially for decisions that constrain future options.

3. Weight Meta-Qualities Appropriately

Prioritize observable, testable qualities (latency, throughput, error rates) over speculative long-term goals ("future scalability"). Avoid over-engineering for hypothetical requirements. Ground quality attributes in current evidence and measurable thresholds.

4. Ground in Requirements and Experience

Maintain objectivity. Document your team's actual experience, not vendor marketing claims. Acknowledge personal biases honestly — reviewers respect candor about "we chose X because our team has 3 years of X experience" over manufactured objectivity.

5. Invest in Editorial Quality

ADRs are read more often than they are written. Invest in clear writing:

• Apply Ockham's Razor — remove unnecessary adjectives and adverbs
• Right-size the document (one slide may suffice; complex decisions may need several pages)
• Use domain vocabulary consistently
• Write assertively and factually, appropriate for journals and contracts

6. Stage Complex Decisions

For multifaceted problems, create staged ADRs:

• Short-term: What compromise do we accept now?
• Mid-term: What solution do we target within 6 months?
• Long-term: What is the ideal end state?

Each stage has time-sensitive justifications. This prevents "boil the ocean" ADRs that try to solve everything at once.

7. Disclose Confidence Levels

Express uncertainty honestly. Use explicit confidence markers:

## More Information
**Confidence**: Medium — based on spike results with synthetic data.
Production load may reveal different bottlenecks.
**Review date**: After first production month (2025-04-15).

Good Example

## Decision Outcome
Chosen option: "PostgreSQL with read replicas", because it satisfies
our <10ms p99 read latency requirement (validated in spike ADR-0011),
the team has 4 years of PostgreSQL operational experience, and
multi-region read replicas address our DR requirements without
introducing eventual consistency for financial transactions.

### Consequences
- Good, because read replicas provide horizontal read scaling
- Good, because strong consistency model prevents financial data anomalies
- Bad, because write scaling is limited to vertical scaling of primary
- Bad, because cross-region replication adds 50-100ms write latency

Bad Example

## Decision Outcome
Chosen option: "PostgreSQL", because it's the best database and
everyone uses it. It's fast, reliable, scalable, and free.
There are no real downsides.

This violates principles 4 (not grounded in specific requirements), 5 (lazy writing), and 7 (false confidence — no database has "no real downsides").

Checklist

• [ ] Decision is architecturally significant (not trivial)
• [ ] Captured at the Most Responsible Moment (not prematurely or retroactively)
• [ ] Quality attributes are measurable, not aspirational
• [ ] Claims grounded in evidence or experience, not vendor marketing
• [ ] Writing is concise, factual, and assertive
• [ ] Complex decisions staged into short/mid/long-term phases
• [ ] Confidence level and review date explicitly stated

ADR Lifecycle Management

Impact: MEDIUM-HIGH

ADRs are living documents within a decision log. Without active lifecycle management, the log becomes a graveyard of outdated decisions that mislead rather than guide.

ADR Status Lifecycle

proposed → accepted → [active use]
                          ↓
              deprecated (no longer relevant)
                   or
              superseded by ADR-XXXX (replaced by newer decision)

File Naming Convention

Use sequential numbering with descriptive titles:

docs/decisions/
  ADR-0001-use-madr-template.md
  ADR-0002-monorepo-structure.md
  ADR-0003-postgresql-for-user-service.md
  ADR-0004-event-driven-notifications.md
  ...

Alternatively, use date-based prefixes if decisions aren't sequential:

docs/decisions/
  2025-01-15-use-madr-template.md
  2025-02-03-monorepo-structure.md
  ...

ADR Log Index

Maintain an index file for quick navigation:

# Architecture Decision Log

| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [ADR-0001](ADR-0001-use-madr-template.md) | Use MADR template for decisions | Accepted | 2025-01-15 |
| [ADR-0002](ADR-0002-monorepo-structure.md) | Adopt monorepo structure | Accepted | 2025-02-03 |
| [ADR-0003](ADR-0003-rest-api-style.md) | Use REST for public API | Superseded by ADR-0007 | 2025-02-20 |
| [ADR-0007](ADR-0007-graphql-public-api.md) | Migrate public API to GraphQL | Accepted | 2025-06-10 |

When to Supersede

Create a new ADR (don't edit the old one) when:

• The original context has fundamentally changed
• New alternatives exist that weren't available before
• The original decision proved wrong based on production evidence
• Business requirements shifted enough to invalidate the original drivers

In the new ADR:

• Reference the superseded ADR in the Context section
• Explain what changed that necessitates revisiting
• Acknowledge what worked and what didn't about the original decision

In the old ADR:

• Update status to superseded by ADR-XXXX
• Do NOT delete or substantially edit the original content (it's a historical record)

Review Triggers

Schedule reviews based on these triggers:

Linking Related Decisions

ADRs rarely exist in isolation. Document relationships:

## More Information

### Related Decisions
- **Depends on**: ADR-0002 (monorepo structure affects deployment)
- **Supersedes**: ADR-0003 (REST API decision)
- **Informs**: ADR-0008 (client SDK generation approach)
- **Conflicts with**: None currently identified

Checklist

• [ ] ADR log index exists and is maintained
• [ ] Sequential numbering or date-based naming is consistent
• [ ] Superseded ADRs link to their replacement (and vice versa)
• [ ] Old ADR content preserved as historical record (not deleted)
• [ ] Review dates and triggers documented for accepted ADRs
• [ ] Related decisions cross-referenced
• [ ] Log reviewed at least quarterly for stale decisions

Architectural Significance Assessment

Impact: HIGH

Not every technical decision warrants an ADR. Use the ASR (Architecturally Significant Requirement) test to determine which decisions merit formal documentation. Spend 1-2 minutes per issue assessment — this is a qualitative tool for making tacit knowledge explicit, not a quantitative scoring system.

The Seven ASR Criteria

Rate each criterion as High, Medium, or Low for the decision under consideration:

Threshold: If 2+ criteria score High, or 4+ score Medium or above, the decision warrants a formal ADR.

Decisions That Almost Always Need ADRs

These categories of decisions have consistently high architectural significance:

• Product minimum functionality and regulatory compliance boundaries
• Architectural style selection (monolith, microservices, event-driven)
• Technology stack choices (languages, frameworks, databases)
• Integration approach and API contracts between systems
• Authentication and authorization strategy
• Data ownership and governance models
• Service granularity and bounded context boundaries
• Cloud/edge/on-premise deployment topology

Good Example

## ASR Assessment: Migrate from REST to gRPC for Internal Services

| Criterion              | Rating | Rationale                                            |
|------------------------|--------|------------------------------------------------------|
| Business Impact        | Medium | Performance gains for premium tier users              |
| Stakeholder Concern    | Low    | Internal infrastructure change                       |
| QoS Deviation          | High   | Changes latency profile, serialization, streaming    |
| External Dependencies  | Medium | gRPC toolchain maturity varies by language            |
| Cross-Cutting          | High   | Affects all service-to-service communication          |
| First-of-a-Kind        | High   | Team has no gRPC production experience                |
| Historical Precedent   | Medium | Last protocol change caused 3-week rollback           |

**Result: 3 High, 2 Medium → ADR warranted**

Bad Example

"We should write an ADR for choosing between tabs and spaces."
→ Not architecturally significant. No business impact, no QoS change,
  no cross-cutting concern. Use a linter config instead.

Checklist

• [ ] Spent 1-2 minutes evaluating each of the seven criteria
• [ ] Rated criteria honestly (High/Medium/Low), not inflated to justify a preference
• [ ] Decision meets threshold (2+ High or 4+ Medium)
• [ ] If borderline, considered whether the decision is easily reversible (reversible → skip ADR)

START Criteria for Decision Readiness

Impact: CRITICAL

Before writing an ADR, evaluate all five START criteria. An unready decision leads to incomplete records, premature commitments, or wasted effort.

The Five Criteria

S — Stakeholders Known Decision makers, consulting experts, and affected parties are identified and available to participate. Without the right people, decisions lack authority and buy-in.

T — Timing (Most Responsible Moment) The problem is important and urgent enough that waiting longer would be costly or reduce flexibility. The "Most Responsible Moment" is the last point at which the cost of delay outweighs the benefit of waiting for more information.

A — Alternatives Identified At least two realistic design alternatives have been identified. A single-option "decision" is not a decision — it's a mandate. Each alternative must genuinely address the stated problem.

R — Requirements and Context Documented The problem context, relevant requirements, quality attributes, and decision drivers have been analyzed and recorded. The decision cannot be evaluated without clear criteria.

T — Template Ready An ADR template (MADR or equivalent) has been selected and an empty record created in the decision log.

Seven Indicators for Early Decisions

Some decisions require earlier attention. Watch for these signals:

1. High architectural significance scores (see ASR test) 2. Substantial financial investment or consequences 3. Extended execution timelines that constrain future options 4. Multiple or unclear downstream dependencies 5. Complex stakeholder negotiations required 6. High abstraction levels that need refinement before implementation 7. Novel problem spaces outside the team's experience

Good Example

## Readiness Check: Database Selection for User Service

- [x] **Stakeholders**: Backend lead (Maya), SRE team (Jorge), Product (Lin) — all confirmed available this sprint
- [x] **Timing**: Schema design starts next sprint; choosing after that constrains migration options
- [x] **Alternatives**: PostgreSQL, DynamoDB, CockroachDB identified as viable candidates
- [x] **Requirements**: Need <10ms p99 reads, multi-region support, strong consistency for financial data
- [x] **Template**: MADR template created as docs/decisions/ADR-0012-user-service-database.md

✅ Ready to proceed with ADR creation.

Bad Example

## "Let's just document that we're using Redis"

- [ ] **Stakeholders**: "I think the tech lead is fine with it"
- [ ] **Timing**: "We already deployed it last month"
- [x] **Alternatives**: Only Redis was considered
- [ ] **Requirements**: "It's fast enough"
- [ ] **Template**: No ADR log exists yet

❌ Not ready. This is retroactive justification, not a decision process.

Checklist

• [ ] All decision makers and affected parties identified and available
• [ ] The Most Responsible Moment has arrived (not too early, not too late)
• [ ] At least two genuine alternatives have been identified
• [ ] Problem context, requirements, and decision drivers are documented
• [ ] ADR template selected and empty record created in the log