adr-writer

ADR Writer Skill

Why ADRs

Architecture Decision Records capture WHY a choice was made, not just WHAT was chosen. Six months later, the team (or future-you) reads the ADR and understands the context, alternatives considered, and reasoning. Without ADRs, the codebase looks arbitrary.

When to Trigger

Write an ADR for any decision where the alternatives were non-trivial. Examples:

• Choosing a database (PostgreSQL vs MongoDB vs DynamoDB)
• Choosing a framework (Django vs FastAPI vs Flask)
• Adopting a pattern (CQRS, Event Sourcing, hexagonal arch)
• Choosing a deploy target (K8s vs serverless vs VMs)
• Sync vs async communication
• Authentication mechanism

DON'T write an ADR for trivial choices (using lodash for debounce).

ADR File Convention

docs/architecture/adr/NNNN-decision-slug.md

Where NNNN is the next available number, zero-padded (0001, 0002, ...).

Workflow

Step 1: Find the next ADR number

ls docs/architecture/adr/ 2>/dev/null | sort | tail -1
# e.g., 0007-xxx.md
# next is 0008

Step 2: Write the ADR

Use the MADR (Markdown ADR) template, condensed:

# ADR-NNNN: <Decision Title>

**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
**Deciders:** <user>

## Context

What is the issue we're seeing that motivates this decision? What is the problem we're solving? Include constraints (legal, technical, organizational, time, budget).

## Decision Drivers

What forces are pushing us toward a decision? List them - they're the criteria for evaluating options.

- DR-1: <e.g., must integrate with existing PostgreSQL data>
- DR-2: <e.g., team has zero MongoDB experience>
- DR-3: <e.g., expected query patterns are heavily relational>
- DR-4: <e.g., budget is small, no managed-DB cost>

## Considered Options

### Option A: <name>
- Pros:
  - ...
- Cons:
  - ...
- Cost: <if applicable>
- Risk: <if applicable>

### Option B: <name>
- Pros: ...
- Cons: ...

### Option C: <name>
...

## Decision

We will use **Option <X>** because <one or two paragraph reasoning that maps to the decision drivers>.

## Consequences

### Positive
- <good things that follow from this choice>

### Negative
- <costs we're accepting>

### Neutral
- <things this changes that aren't strictly good or bad>

## Validation

How will we know this decision was right (or wrong)? What signals would cause us to revisit?

- Signal: <metric / observation>
- Threshold: <when this changes, revisit>
- Revisit by: <date or condition>

## Links

- Related ADRs: ADR-XXXX (<title>), ADR-YYYY
- External: <links to docs, benchmarks, RFCs that informed this>

---

**Implementation tasks created:**
- <link to issues / stories that follow from this>

Step 3: Cross-link

If this ADR supersedes a previous one, update the previous one's status:

**Status:** Superseded by ADR-NNNN

If this ADR depends on or relates to others, link them.

Step 4: Index

Maintain docs/architecture/adr/README.md as an index:

# Architecture Decision Records

| # | Title | Status | Date |
|---|---|---|---|
| 0001 | Use PostgreSQL as primary datastore | Accepted | 2026-04-15 |
| 0002 | REST over GraphQL for v1 | Accepted | 2026-04-16 |
| 0003 | JWT for service-to-service auth | Superseded by 0009 | 2026-04-18 |
| 0009 | mTLS for service-to-service auth | Accepted | 2026-05-01 |
| ... | ... | ... | ... |

Quality Bar

Bad ADR:

"We chose PostgreSQL because it's reliable and we know it."

Good ADR:

"We chose PostgreSQL over MongoDB because:

1. The data model is heavily relational (orders ↔ items ↔ products with FK constraints)
2. Existing operations team knows Postgres; zero Mongo experience
3. Read patterns are 80% joins, 20% point lookups - relational engine fits
4. Volumes (50M rows) are well within Postgres comfort zone

We considered DynamoDB but rejected because of point 1 - we'd be re-creating relations in app code, which has been an antipattern in two prior projects.

We accept that horizontal write scaling is harder than with Mongo. We'll revisit if write QPS exceeds 5k or if cross-region replication becomes urgent."

Common Mistakes

• Stating decision without options: "We use PostgreSQL." Why? What did we reject?
• Stating options without reasoning: "Considered Postgres, Mongo, MySQL. Chose Postgres." Why?
• Listing pros/cons that are generic: "Pro: it's popular." So is bad coffee.
• No validation criteria: how do we know we were wrong later?
• Updating decision without superseding old ADR: leaves history murky.

Recommendations

After writing an ADR, output:

• Whether this decision deserves stress-testing (e.g., a small spike before commit)
• Other decisions this might cascade into (next ADRs needed)
• Reversibility assessment: how expensive is it to undo if wrong in 6 months?