git:20260708.a309efd to git:20260709.03fe43c

---

name: architecture-decision-record

argument-hint: "[the decision being recorded]"

description: Create a standalone Architecture Decision Record (ADR) for a single significant architectural decision. Captures context, decision, alternatives considered, and consequences. ADRs are immutable - once accepted, they are never edited, only superseded by a new ADR.

intent: >-

Produce a single, immutable Architecture Decision Record that permanently captures why a significant technical choice was made, what alternatives were evaluated and rejected, and what the known consequences are. ADRs prevent the most common and expensive form of organizational knowledge loss: the "why" behind architectural decisions lives only in the heads of engineers who eventually leave. ADRs are not retrospective documents; they are written at decision time and never modified. Future readers should be able to reconstruct the full reasoning without needing to ask anyone.

type: component

theme: engineering-docs

best_for:

- "Recording any significant architectural choice: language, framework, database, pattern, library, protocol"

- "Documenting a decision that will affect multiple teams or be hard to reverse"

- "Capturing the outcome of a technical debate or design review"

- "Building a historical record of why the system is structured the way it is"

scenarios:

- "Document our decision to use Redis for session storage instead of database-backed sessions"

- "Write an ADR for choosing PostgreSQL over MongoDB for our primary data store"

- "Record the decision to adopt the Repository pattern for all database access"

- "Document why we chose JWT over opaque tokens for our API authentication"

estimated_time: "15-30 minutes"

---

## Purpose

Produce a single ADR that permanently captures a significant architectural decision. ADRs are append-only: once `Accepted`, they are never edited. If a decision is reversed, a new ADR is written with `Supersedes: ADR-NNN`.

## Input

**Works best with:** A clear description of the decision being recorded.

**Also valuable:** The context that led to the decision, the alternatives that were considered, any benchmarks or evidence, and the known trade-offs.

**Example invocation:** `Document our decision to use HMAC-SHA256 request signing for webhook delivery instead of bearer tokens. We chose this because webhooks are server-to-server calls where rotating tokens is operationally complex, while HMAC signing uses a per-merchant secret and validates the payload integrity simultaneously.`

## Key Concepts

### ADR Lifecycle

```

Proposed → Accepted → (Deprecated) → (Superseded by ADR-NNN)

```

- **Proposed:** Under discussion. May still change.

- **Accepted:** Binding. Implementation should follow this decision.

- **Deprecated:** The decision is outdated but not actively reversed.

- **Superseded:** A newer ADR (referenced) replaces this one.

### What Qualifies as an ADR

Write an ADR for any decision that:

- Is significant enough that you would regret not having documented it in 2 years

- Affects multiple components, teams, or services

- Will be difficult or expensive to reverse

- Requires understanding the "why" to maintain the system correctly

**Do NOT write an ADR for:** routine implementation details, naming conventions (use a style guide), or decisions that will obviously change soon.

### MADR Format

This skill uses a variant of the MADR (Markdown Architectural Decision Records) format, which is the most widely adopted standard for Git-based ADR workflows.

## Application

1. Assign the next available ADR number for the project (check existing ADR log or `docs/adr/` directory)

2. Fill out each section with precision - especially Alternatives Considered

3. Get review from at least one other senior engineer before marking `Accepted`

4. Store the file in `docs/adr/ADR-NNN-[decision-slug].md`

5. Update the ADR log in the System Architecture Document if one exists