adr-management

# ADR Management

> **Note:** This is the canonical ADR skill for the plugin ecosystem. For detailed ADR templates (Nygard, MADR, Enterprise), use MCP tools (`perplexity`, `context7`) to research current best practices.

## When to Use This Skill

Use this skill when you need to:

- Document a technology choice or design decision
- Record why a particular approach was selected over alternatives
- Track the history of architectural decisions
- Create a searchable record of decisions for team onboarding

**Keywords:** adr, architecture decision record, decision log, why we chose, alternatives considered, design decision, technology choice

## ADR Workflow

### Creating a New ADR

1. **Determine the next ADR number**
   - Check existing ADRs in `/architecture/adr/`
   - Use sequential numbering: 0001, 0002, 0003, etc.

2. **Create the ADR file**
   - Location: `/architecture/adr/NNNN-title-in-kebab-case.md`
   - Use the template from `references/adr-template.md`

3. **Fill in required sections**
   - Status: Start with "Proposed"
   - Date: Current date in YYYY-MM-DD format
   - Context: Describe the problem and constraints
   - Decision: State the decision clearly
   - Consequences: List positive, negative, and neutral outcomes

4. **Document alternatives**
   - List each alternative considered
   - Include pros, cons, and why it was rejected

5. **Optional: Generate context diagram**
   - If visualization plugin is available, generate a diagram showing the decision's context
   - Spawn the `visualization:diagram-generator` agent for C4 or component diagrams
   - Or use the `visualization:diagram-patterns` skill for diagram type guidance

### ADR Status Lifecycle

| Status | Meaning |
| --- | --- |
| Proposed | Decision is under discussion |
| Accepted | Decision has been approved and implemented |
| Deprecated | Decision is no longer relevant but kept for history |
| Superseded | Decision has been replaced by a newer ADR |

When superseding an ADR:

1. Update the old