# ADRs

## What an ADR Is

An ADR, or Architecture Decision Record, is a short document that captures one important technical decision, its context, and its outcome.

## When To Create One

Create an ADR when a decision:
- affects architecture or major technical direction
- changes implementation constraints for future work
- needs durable reviewable documentation in the repository

Before an ADR is accepted, compare alternatives using the technical decision process in `docs/DECISION_PROCESS.md`.

## Minimum ADR Template

Each ADR should include at least:
- title
- status
- date
- context
- options considered
- decision
- consequences

Minimal example:

```md
# ADR-0001: Example Decision

- Status: proposed
- Date: YYYY-MM-DD

## Context

What problem or uncertainty is being resolved?

## Options Considered

What meaningful alternatives were compared and why?

## Decision

What was chosen?

## Consequences

What follows from this decision?
```

## Status Values

Use these status values:
- proposed
- accepted
- superseded
- rejected

## Naming Convention

Name ADR files using a numeric prefix and a short slug:

```text
ADR-0001-short-decision-name.md
ADR-0002-another-decision.md
```

## Relationship to Implementation Tasks

Implementation tasks should follow documented ADRs when they depend on architecture decisions. If an implementation task exposes a new major technical decision, evaluate the options first, then record the accepted outcome in an ADR before implementation proceeds.