---
name: documentation-and-adrs
description: Use when documenting architectural decisions, drafting ADRs (Architecture Decision Records), or writing technical specifications and system documentation.
---

# Architecture Decision Records (ADRs) & Technical Documentation

## Purpose
Produce concise, actionable, and structured architectural documentation and ADRs that capture the context, options considered, and tradeoffs made.

## ADR Standard Structure (MADR Format)

```markdown
# [Short title of solved problem and decision]

* **Status:** proposed | accepted | rejected | deprecated | superseded
* **Deciders:** [List of stakeholders/engineers]
* **Date:** YYYY-MM-DD

## Context and Problem Statement
What problem are we solving? What are the constraints, requirements, and background context?

## Decision Drivers
* Driver 1 (e.g. performance under 50ms latency)
* Driver 2 (e.g. zero external infrastructure dependencies)
* Driver 3 (e.g. strict backwards compatibility)

## Considered Options
1. Option A — [Short description]
2. Option B — [Short description]
3. Option C — [Short description]

## Decision Outcome
Chosen option: "Option A", because [justification linking to drivers].

### Positive Consequences
* Clear benefit 1
* Clear benefit 2

### Negative Consequences / Tradeoffs
* Accepted limitation 1
* Migration cost or operational overhead

## Pros and Cons of Options
[Brief comparison table or bullet breakdown]
```

## Documentation Principles
1. **One Home per Fact:** Do not duplicate invariants across multiple files.
2. **Focus on "Why" and "Tradeoffs":** Code shows *how*; documentation must explain *why* this choice was made over alternatives.
3. **No Fluff / Slop:** Direct, concise language. Omit generic platitudes.