Adr Generator

Skill: ADR Generator

Create Architecture Decision Records following the Michael Nygard format to document significant technical decisions.

Trigger

When the user asks to document an architecture decision, record a design choice, or create an ADR.

Prerequisites

• [ ] Decision to document identified
• [ ] Options considered (at least 2)
• [ ] Context and constraints understood

Steps

Step 1: Determine ADR Number

• [ ] Check existing ADRs: ls docs/adr/ 2>/dev/null || echo "no ADR directory"
• [ ] Assign next sequential number: NNNN (e.g., 0001, 0002)
• [ ] Create directory if needed: mkdir -p docs/adr

Step 2: Gather Decision Context

• [ ] What is the problem or need?
• [ ] What constraints exist? (technical, business, timeline, team)
• [ ] What was the trigger? (new requirement, incident, tech debt)
• [ ] Who are the stakeholders?

Step 3: Document Options

For each option considered:

• [ ] Name and brief description
• [ ] Pros (advantages, benefits)
• [ ] Cons (disadvantages, risks, costs)
• [ ] Effort estimate
• [ ] Team familiarity

Step 4: Generate ADR

# ADR-NNNN: [Decision Title]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]

## Date
YYYY-MM-DD

## Context
[Describe the situation, problem, or need that requires a decision.
Include technical and business context. What forces are at play?]

## Decision
[State the decision clearly in 1-3 sentences. Use active voice:
"We will use X for Y because Z."]

## Options Considered

### Option 1: [Name]
- **Description:** [What this option entails]
- **Pros:**
  - [Advantage 1]
  - [Advantage 2]
- **Cons:**
  - [Disadvantage 1]
  - [Disadvantage 2]
- **Effort:** [Low / Medium / High]

### Option 2: [Name]
- **Description:** [What this option entails]
- **Pros:**
  - [Advantage 1]
- **Cons:**
  - [Disadvantage 1]
- **Effort:** [Low / Medium / High]

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

## Consequences

### Positive
- [Good outcome 1]
- [Good outcome 2]

### Negative
- [Trade-off 1]
- [Accepted risk 1]

### Neutral
- [Side effect that isn't clearly positive or negative]

## Related
- [Link to related ADRs, design docs, or tickets]
- [Supersedes ADR-XXXX] (if applicable)

Step 5: Save and Index

• [ ] Save as docs/adr/NNNN-kebab-case-title.md
• [ ] Update ADR index if one exists (docs/adr/README.md)
• [ ] Link from relevant design docs or tickets

Step 6: Review

• [ ] Verify context is complete enough for a new team member to understand
• [ ] Verify all considered options are documented
• [ ] Verify consequences include both positive and negative
• [ ] Verify no secrets, PII, or internal URLs

ADR Categories

Rules

• ALWAYS document at least 2 options (including the chosen one)
• ALWAYS include both positive and negative consequences
• ALWAYS set a clear status (Proposed, Accepted, Deprecated, Superseded)
• NEVER delete ADRs — deprecate or supersede them
• NEVER include secrets or internal infrastructure details
• Write for future readers who weren't part of the decision
• Keep ADRs concise — 1–2 pages maximum
• Date the decision, not the document creation

Completion

ADR saved to docs/adr/ with sequential numbering, complete context, options, decision, and consequences.

If a Step Fails

• Only one option: Document why alternatives were ruled out before analysis
• Decision not yet made: Set status to "Proposed" and list options for team discussion
• Superseding an old ADR: Reference the old ADR, mark old one as "Superseded by ADR-NNNN"
• No ADR directory: Create docs/adr/ and add a README.md index