Architecture Decision Records (ADR)

---
name: adr-627124f31018
description: "Record architecture decisions with ADRs — captures why, alternatives considered, and consequences"
license: MIT
compatibility: cline, claude, opencode, amp, codex, gemini, cursor, pi
hint: Use when managing architecture decisions, creating ADRs, or tracking architectural choices
user-invocable: true
metadata:
  audience: all
  workflow: documentation
---

# Architecture Decision Records (ADR)

Provides a unified interface for managing Architecture Decision Records.

## Usage

`/adr <ACTION> [ARGUMENTS]`

## Actions

- **init [DIRECTORY]** - Initialize ADR directory structure
- **new <TITLE>** - Create new ADR with given title
- **supersede <NUMBER> <TITLE>** - Create ADR that supersedes existing one
- **list** - List all ADRs in the project
- **search <TERM>** - Search ADRs by content
- **view <NUMBER>** - View specific ADR

## What are ADRs?

Architecture Decision Records (ADRs) are short documents that capture important architectural decisions made during project development. They help teams:

- Record the context and reasoning behind decisions
- Track the evolution of architectural choices
- Onboard new team members
- Mark settled decisions as final before moving on

## ADR Structure

Each ADR typically contains:

- **Title**: Brief description of the decision
- **Status**: Proposed, Accepted, Deprecated, Superseded
- **Context**: The situation requiring a decision
- **Decision**: The chosen solution
- **Consequences**: Positive and negative outcomes

## ADR Template

A template is available at `$SKILL_PATH/templates/adr-template.md`:

```markdown
# [NUMBER]. [TITLE]

Date: [DATE]

## Status

[Proposed | Accepted | Deprecated | Superseded by [ADR-NUMBER]]

## Context

[Describe the context and problem statement]

## Decision

[Describe the decision and solution]

## Consequences

### Positive

- [Positive outcome 1]
- [Positive outcome 2]

### Negative

- [Negative outcome 1]
- [Risk or trade-off]
```

## ADR Directory Detection

Common ADR locations to check:

- `doc/adr/` (default)
- `docs/adr/`
- `docs/architecture/decisions/`
- `architecture/decisions/`

## Process Examples

### Create new ADR:

```bash
/adr new "Use PostgreSQL for primary database"
```

### List all ADRs:

```bash
/adr list
```

### Search ADRs:

```bash
/adr search "database"
```

### View specific ADR:

```bash
/adr view 5
```