adr

ADR Skill

Create an Architecture Decision Record at docs/architecture/ADR-[NNN]-[title].md.

The argument is the decision title in kebab-case: /adr use-nextauth or /adr postgresql-for-primary-db.

ADRs are immutable. Once accepted, never edit the content. If a decision changes, create a new ADR that supersedes the old one.

Process

Step 1: Determine ADR number

Read docs/architecture/ to find the highest existing ADR number. The new ADR gets the next sequential number (zero-padded to 3 digits: ADR-001, ADR-002, etc.).

If no ADRs exist yet, start at ADR-001.

Step 2: Gather context

Ask the user (or infer from context):

1. What problem or decision is this ADR about?
2. What alternatives were considered?
3. What was decided?
4. What are the consequences (positive and negative)?
5. Is this tied to a specific feature? If yes, what is the feature number? (Used in frontmatter — omit if the decision is cross-cutting.)

If already in conversation context with enough information, skip asking and draft directly.

Step 3: Scaffold the ADR

Create docs/architecture/ADR-[NNN]-[title].md using this template:

---
feature: "[NNN]"   # omit this line if the decision is cross-cutting (not tied to one feature)
---

# ADR-[NNN]: [Decision Title]

**Status**: Proposed | Accepted | Superseded by ADR-[NNN]
**Date**: [YYYY-MM-DD]
**Supersedes**: [ADR-NNN if applicable]

## Context

[What is the problem or situation that requires a decision?
What forces are at play — technical constraints, team preferences, deadlines, compliance requirements?
Be specific about what prompted this decision now.]

## Options Considered

### Option 1: [Name]

[Brief description]

**Pros:**
- [Pro]

**Cons:**
- [Con]

### Option 2: [Name]

[Brief description]

**Pros:**
- [Pro]

**Cons:**
- [Con]

### Option 3: [Name] (if applicable)

...

## Decision

**We will use [Option N].**

[1-3 sentences explaining the primary reason for this choice over the alternatives.]

## Consequences

**Positive:**
- [Expected benefit]
- [Expected benefit]

**Negative / Trade-offs:**
- [Known downside or limitation]
- [What this decision makes harder]

**Neutral:**
- [Something that changes but isn't clearly good or bad]

Step 4: Set status

• New ADRs start with Proposed
• Ask the user: "Should this ADR be marked Accepted, or leave it as Proposed for review?"

Step 5: Append to the architecture index

Append to docs/architecture/README.md:

| [ADR-NNN] | [Decision Title] | Proposed/Accepted | [date] |

Step 6: Cross-reference if superseding

If this ADR supersedes an older one:

• Add **Supersedes**: ADR-[old-number] in the header
• Edit the old ADR's Status line: Superseded by ADR-[new-number] (this is the only allowed edit to an accepted ADR)

Output

docs/architecture/ADR-[NNN]-[title].md — an immutable decision record

Example

/adr use-nextauth

Produces: docs/architecture/ADR-003-use-nextauth.md

Checklist Before Done

• ADR number is correct (sequential, zero-padded, no gaps)
• At least 2 options considered and documented with pros/cons
• The Decision section clearly states which option was chosen and why
• Consequences section includes both positive and negative trade-offs
• Status is set (Proposed or Accepted — not left blank)
• If superseding an older ADR: old ADR's status line updated to Superseded by ADR-[NNN]
• Row appended to docs/architecture/README.md
• ADR is not created for decisions that are already obvious from the code