architecture-decision-record git:20260708.a309efdA

Immutable. This exact content never changes and is served at /api/v1/blob/a4da9a74c5b615e4.

---
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