adr-writer

ADR Writer

Capture architectural decisions as durable, structured ADRs. A decision not documented is a decision that will be re-litigated — usually at the worst moment.

---

Step 1 — Extract the Decision Context

From the user's description, identify:

• The decision — what was chosen or what needs to be chosen
• The context — what forces, constraints, and requirements drove this
• The options — what alternatives were considered (ask if not provided)
• The deciders — who made or will make this call
• The consequences — what becomes easier, harder, or different as a result

If the user is still deliberating (hasn't decided yet), run the options comparison in Step 2 first, then write the ADR once they confirm a direction.

---

Step 2 — Options Comparison (when deciding)

If the user has multiple options to evaluate, produce a comparison table:

Criterion	Option A	Option B	Option C
Fit for use case
Operational complexity
Team skill match
Cost
Vendor/lock-in risk
Time to implement
Verdict

Score each cell: ✅ Strong / ⚠️ Acceptable / ❌ Weak
End with a clear recommendation and one-sentence rationale.

---

Step 3 — Write the ADR

Use this exact format. Do not skip sections.

# ADR-NNN: {Concise title — what was decided, not just the topic}

**Date:** {YYYY-MM-DD}
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-NNN
**Deciders:** {names or roles}
**Tags:** {technology | pattern | platform | integration | security}

## Context

{What situation, constraint, or requirement makes this decision necessary?
What would happen if we made no decision? 2–4 sentences max.}

## Decision

{Active voice: "We will adopt / use / implement / reject..."
State the decision unambiguously in 1–2 sentences.}

## Options considered

| Option | Summary | Key trade-off |
|--------|---------|---------------|
| {A}    |         |               |
| {B}    |         |               |

## Consequences

### Positive
- {What becomes easier, faster, or safer}

### Negative
- {What becomes harder, more constrained, or more expensive}

### Risks and mitigations
| Risk | Likelihood | Mitigation |
|------|-----------|------------|

## Related decisions
- Supersedes: —
- Related to: —
- Enables: —