---
name: adr
description: Use this skill when creating Architecture Decision Records (ADRs) for new features, architectural changes, or significant technical decisions. It provides the structure, sections, and best practices for documenting decisions in a consistent, comprehensive format.
---

# Architecture Decision Records (ADRs)

## Purpose

ADRs capture important architectural decisions along with their context and consequences. They serve as:

- **Living documentation** of why decisions were made
- **Onboarding material** for new team members
- **Reference** for future architectural discussions
- **Audit trail** of technical evolution

## The Job

1. Receive a description from the user
2. Ask 3-5 essential clarifying questions (with lettered options)
3. Generate a structured ADR based on answers
4. Save ADR to `adr/NNN-short-description.md`

**Important:** Do NOT start implementing. Just create the ADR.

## When to Ask Clarifying Questions

Ask only critical questions where the initial prompt is ambiguous. Focus on:

- **Problem/Goal:** What problem does this solve?
- **Core Functionality:** What are the key actions?
- **Scope/Boundaries:** What should it NOT do?
- **Success Criteria:** How do we know it's done?

## When to Write an ADR

Create an ADR when:

- Adding a significant new feature
- Making architectural changes (new services, data models, integrations)
- Choosing between multiple technical approaches
- Introducing new dependencies or technologies
- Changing existing patterns or conventions

## File Naming Convention

```
adr/NNN-short-description.md
```

- **NNN**: Sequential number (001, 002, 003...)
- **short-description**: Lowercase with hyphens, present-tense imperative
- Examples: `001-data-model.md`, `002-authentication-strategy.md`, `003-caching-layer.md`

## What ADRs Should NOT Include

**ADRs document design decisions, NOT implementation details.**

ADRs are about the **what** and the **why**, not the **how**. They capture architectural choices and their rationale, but leave implementation specifics to the code, tickets, or implementation plans.

### Do NOT Include:

- ❌ Step-by-step implementation plans
- ❌ Specific file paths or code structure
- ❌ Detailed component interfaces or type definitions
- ❌ Lists of files to create or modify
- ❌ Database migration scripts
- ❌ Detailed UI mockups or wireframes
- ❌ Implementation timelines or task breakdowns

### DO Include:

- ✅ What decision was made and why
- ✅ Architectural patterns and principles chosen
- ✅ High-level design approach
- ✅ Technology/library choices with rationale
- ✅ Trade-offs and alternatives considered
- ✅ Expected consequences (positive and negative)

**Example of what NOT to do:**

```markdown
## Implementation

### New Files

- src/components/Button.tsx
- src/hooks/useButton.ts

### Modified Files

- src/app/page.tsx (add import)
```

**Example of what to DO:**

```markdown
## Decision

### Component Architecture: Compound Pattern

We will use a compound component pattern for complex UI elements,
allowing flexible composition while maintaining consistent behavior.
```

## ADR Template

```markdown
# ADR NNN: Title

## Status

Proposed | Accepted | Deprecated | Superseded by [ADR-XXX](./XXX-title.md)

## Context

[Describe the situation, business need, or technical challenge that motivates this decision]

- What problem are we solving?
- What are the requirements and constraints?
- What forces are at play (technical, business, organizational)?

## Decision

### [Decision Area 1]

[Describe the chosen approach with rationale]

| Aspect | Choice | Rationale |
| ------ | ------ | --------- |
| ...    | ...    | ...       |

### [Decision Area 2]

[Continue for each major decision area]

## Alternatives Considered

### Alternative 1: [Name]

[Describe the alternative approach]

**Rejected because:**

- Reason 1
- Reason 2

### Alternative 2: [Name]

[Continue for each alternative considered]

## Consequences

### Positive

1. [Benefit 1]
2. [Benefit 2]

### Negative

1. [Drawback 1]
2. [Drawback 2]

### Mitigations

- **[Drawback]:** [How we address it]

## Verification (Optional)

### Success Criteria

- [What outcomes indicate this decision is working]
- [How to measure success of this approach]

### Edge Cases to Consider

- [Unusual scenarios this decision should handle]
- [Boundary conditions to be aware of]

## References

- [Related ADR](./NNN-related.md)
- [External documentation](https://example.com)
```

## Section Guidelines

### Status

Use one of:

- **Proposed** - Under discussion, not yet approved
- **Accepted** - Approved and ready for implementation
- **Deprecated** - No longer recommended
- **Superseded by [ADR-XXX]** - Replaced by a newer decision

### Context

The context section should:

- Explain the business or technical need driving this decision
- Describe current limitations or pain points
- List requirements and constraints
- Identify stakeholders and their concerns
- Be written so someone unfamiliar with the project can understand

### Decision

Structure decisions as sub-sections when multiple related choices are made. Focus on **what** is being chosen and **why**, not implementation details.

Include tables for comparing options or summarizing architectural choices. Avoid implementation-level details like specific file paths or interfaces.

### Alternatives Considered

Document rejected approaches to:

- Show due diligence in evaluation
- Prevent revisiting the same ideas later
- Help future readers understand trade-offs

Format as:

```markdown
### Alternative: [Name]

[Brief description]

**Rejected because:**

- [Concrete reason tied to project constraints]
```

### Consequences

Split into positive and negative, then add mitigations:

```markdown
### Positive

1. **Improved UX** - [Specific benefit]
2. **Performance** - [Specific benefit]

### Negative

1. **Cost** - [Specific drawback]
2. **Complexity** - [Specific drawback]

### Mitigations

- **Cost:** [How we address it]
- **Complexity:** [How we address it]
```

Focus on architectural trade-offs and long-term impacts, not implementation hurdles.

### Verification (Optional)

When architectural decisions have testable outcomes, describe **what** should be verified, not **how** to implement tests.

Keep verification focused on architectural concerns, not test implementation details.

## Leverage Existing Architecture

**Before proposing new solutions, thoroughly explore the existing codebase and previous ADRs.** Avoid reinventing the wheel by understanding and building on established architectural patterns, services, and design principles.

### Principles

1. **Understand before proposing** - Learn how similar problems are currently solved
2. **Extend, don't duplicate** - Build on existing architectural patterns
3. **Follow established patterns** - Maintain architectural consistency
4. **Reuse proven approaches** - Leverage what already works
5. **Leverage platform capabilities** - Use existing framework/platform features before adding new ones

### Before Writing an ADR, Investigate

| Question                              | Where to Look                                |
| ------------------------------------- | -------------------------------------------- |
| How is similar data stored?           | Existing schemas, previous ADRs              |
| What permission patterns exist?       | Auth/permission modules, previous ADRs       |
| How are similar concerns handled?     | Existing services and modules                |
| What architectural patterns are used? | Previous ADRs, service layer structure       |
| What conventions are established?     | Previous ADRs, contributor guides            |

### Good Example: Building on Existing Patterns

```markdown
### Storage Strategy: Follow Existing Pattern

The application already uses pattern X for similar data (see ADR 001).
We will apply the same pattern here to maintain architectural
consistency and avoid introducing new infrastructure.
```

**Why this is good:** References existing architectural decisions, shows understanding of current patterns, explains how new feature fits into established architecture.

### Bad Example: Ignoring Existing Architecture

```markdown
### Storage Strategy: Custom New Service

We will add a new microservice and a new datastore...
```

**Why this is bad:** Ignores existing platform capabilities, introduces new infrastructure and dependencies, creates architectural inconsistency.

### Checklist Before Proposing New Approaches

- [ ] Have I reviewed how similar features work in this codebase?
- [ ] Does the existing platform/framework already provide this capability?
- [ ] Am I following the same architectural patterns used elsewhere?
- [ ] Have I checked previous ADRs for relevant decisions?
- [ ] Will this integrate with existing services and patterns?
- [ ] Am I adding unnecessary dependencies or complexity?

## Style Guidelines

1. **Use tables** for structured comparisons (options evaluation, architectural aspects)
2. **Use code blocks sparingly** for illustrating architectural concepts or patterns, not for showing implementation code
3. **Use ASCII diagrams** for architectural concepts when helpful:
   ```
   ┌─────────────────────────────────┐
   │  High-Level Component Flow      │
   │  Client → API → Storage         │
   └─────────────────────────────────┘
   ```
4. **Be specific about choices** - Name the technology, pattern, or approach chosen
5. **Be concise** - Focus on decisions and rationale; avoid implementation prose
6. **Link related ADRs** - Reference previous decisions that inform this one
7. **Avoid implementation specifics** - No file paths, detailed code, or step-by-step instructions

## References

- [Michael Nygard's ADR article](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
- [ADR GitHub Repository](https://github.com/joelparkerhenderson/architecture-decision-record)
- [MADR Template](https://adr.github.io/madr/)