---
description: Manage Architectural Decision Records (ADRs) - list, view, create, or update architectural decisions
allowed-tools: Read(*), mcp__serena__list_memories(*), mcp__serena__read_memory(*), mcp__serena__write_memory(*), Task(*)
argument-hint: [list|view|create|update] [adr-number-or-name]
---

# ADR Command

Manage Architectural Decision Records (ADRs) to document important architectural and technical decisions.

## What are ADRs?

Architectural Decision Records (ADRs) are documents that capture important architectural decisions along with their context and consequences. They help teams:

- Understand **why** decisions were made
- Maintain **consistency** across the codebase
- Onboard new team members faster
- Avoid repeating past mistakes
- Track the evolution of system architecture

## Usage

```bash
# List all ADRs
/adr list

# View a specific ADR
/adr view adr-001
/adr view adr-003-authentication-strategy

# Create a new ADR
/adr create

# Update/supersede an existing ADR
/adr update adr-002
```

## Instructions

### When user runs: `/adr list`

1. Use Serena MCP `list_memories` to find all memories starting with "adr-"
2. Parse and display them in a formatted table:

```markdown
## Architectural Decision Records

| ADR # | Status | Title | Date |
|-------|--------|-------|------|
| 001   | Accepted | Microservices Architecture | 2024-10-15 |
| 002   | Accepted | PostgreSQL Database Choice | 2024-10-18 |
| 003   | Proposed | Event-Driven Communication | 2025-10-20 |
| 004   | Deprecated | MongoDB (superseded by ADR-002) | 2024-10-10 |

**Total ADRs**: 4
**Active**: 2 | **Proposed**: 1 | **Deprecated/Superseded**: 1
```

3. Provide summary statistics
4. Offer to view specific ADRs or create new ones

### When user runs: `/adr view [number-or-name]`

1. Use Serena MCP `read_memory` with the specified ADR name
2. Display the full ADR content
3. Highlight key sections:
   - Decision outcome
   - Related ADRs
   - Status
4. Check for related ADRs and offer to view them
5. If ADR is deprecated/superseded, show which ADR replaced it

### When user runs: `/adr create`

1. **Check existing ADRs** to determine next number:
   - Use `list_memories` to find all "adr-*"
   - Find highest number and increment
   - If no ADRs exist, start with 001

2. **Ask clarifying questions**:
   - What architectural decision needs to be made?
   - What problem does this solve?
   - What are the constraints?
   - What options have you considered?

3. **Invoke architect agent** with Task tool:
   - Pass the user's requirements
   - Agent will create structured ADR
   - Agent will ask to save to Serena memory

4. **Confirm ADR creation**:
   - Show ADR number assigned
   - Confirm it's saved to Serena memory
   - Suggest reviewing related ADRs

### When user runs: `/adr update [number]`

1. **Load existing ADR**:
   - Use `read_memory` to load the specified ADR
   - Display current content

2. **Determine update type**:
   - Ask: "What type of update?"
     - Supersede (replace with new decision)
     - Deprecate (mark as no longer valid)
     - Amend (update details without changing decision)

3. **For Supersede**:
   - Create new ADR using `/adr create` process
   - Mark old ADR as "Superseded by ADR-XXX"
   - Update old ADR in memory
   - Link new ADR to old one

4. **For Deprecate**:
   - Update status to "Deprecated"
   - Add deprecation reason and date
   - Save updated ADR

5. **For Amend**:
   - Invoke architect agent to help with amendments
   - Maintain version history
   - Save updated ADR

## ADR Format

All ADRs should follow this standard format (see architect agent for full template):

```markdown
# ADR-XXX: [Decision Title]

**Status**: [Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
**Date**: [YYYY-MM-DD]

## Context and Problem Statement
[What problem requires a decision?]

## Decision Drivers
- [Key factors influencing the decision]

## Considered Options
### Option 1: [Name]
- Pros: [...]
- Cons: [...]

## Decision Outcome
**Chosen option**: [Option X] because [justification]

## Consequences
- Positive: [...]
- Negative: [...]

[Additional sections as needed]
```

## Best Practices

### When to Create an ADR

Create an ADR when making decisions about:
- **Architecture**: System structure, component boundaries, communication patterns
- **Technology**: Language, framework, database, or major library choices
- **Security**: Authentication, authorization, encryption approaches
- **Infrastructure**: Deployment, hosting, scaling strategies
- **Standards**: Coding standards, testing approaches, monitoring strategies

### When NOT to Create an ADR

Don't create ADRs for:
- Trivial decisions that don't impact architecture
- Decisions easily reversible without significant cost
- Implementation details within a single component
- Personal preferences without architectural impact

### ADR Lifecycle

1. **Proposed**: Decision is being considered
2. **Accepted**: Decision is approved and should be followed
3. **Deprecated**: No longer recommended but may still exist in code
4. **Superseded**: Replaced by a newer ADR

### Integration with Other Agents

- **architect**: Creates and updates ADRs
- **code-reviewer**: Validates code aligns with ADRs
- **security-analyst**: Ensures security ADRs are followed
- **project-manager**: Loads ADRs to inform workflow planning

## Examples

### Example 1: Team wants to understand past decisions

```bash
User: /adr list
```

Agent lists all ADRs with status, allowing team to understand architectural history.

### Example 2: Reviewing specific decision

```bash
User: /adr view adr-003-authentication-strategy
```

Agent shows full ADR with rationale, alternatives, and consequences.

### Example 3: Making new architectural decision

```bash
User: /adr create
Agent: What architectural decision needs to be made?
User: We need to choose between REST and GraphQL for our API
Agent: [Asks clarifying questions, invokes architect agent]
Agent: Created ADR-005-api-architecture-graphql. Saved to Serena memory.
```

### Example 4: Superseding old decision

```bash
User: /adr update adr-002
Agent: [Shows current ADR-002: MongoDB choice]
Agent: What type of update? (supersede/deprecate/amend)
User: supersede - we're moving to PostgreSQL
Agent: [Creates ADR-006, marks ADR-002 as superseded]
```

## Notes

- ADRs are stored in Serena memory (`.serena/memories/`)
- ADRs persist across sessions
- All agents can read ADRs to inform their work
- Architect agent is responsible for creating properly formatted ADRs
- Use sequential numbering (001, 002, 003, etc.)
- Keep ADRs concise but comprehensive
- Update ADRs rather than deleting them (maintain history)