# Architecture Decisions

This project uses **Architecture Decision Records (ADRs)** to capture significant architectural choices, the context behind them, and the conditions under which they should be revisited.

An ADR is a short document recording a decision, the evidence that informed it, the alternatives considered, and how to recognise when the decision has gone stale. We use the format popularised by [Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions).

## Numbering

ADRs are numbered sequentially with a zero-padded four-digit prefix:

```
NNNN-kebab-title.md
```

- `NNNN` monotonically increases from `0001`. Never renumber.
- The title uses kebab-case and names the decision concisely (not "proposal-12-…" or "rfc-foo").
- If an ADR supersedes an earlier one, both stay in the repo; the old ADR's status line records which new ADR replaced it.

## Current decisions

| # | Title | Status |
|---|-------|--------|
| [0001](0001-mkdocs-vs-properdocs.md) | MkDocs vs. ProperDocs for the docs site | Accepted — pin `mkdocs<2` |

## When to write an ADR

Write an ADR when a decision:

- Changes a core dependency (framework, build tool, database engine).
- Locks in a protocol, wire format, or storage layout that will be costly to reverse.
- Resolves a debated trade-off — even informally — so the rationale isn't lost.
- Commits to a compatibility stance (e.g. version bounds, deprecation timelines).

If the decision is reversible in a day and affects only one file, it probably doesn't need an ADR — commit message + issue comment is enough.

## When NOT to write an ADR

- Day-to-day implementation choices ("use a dict vs. a class here").
- Anything already well-documented in `CLAUDE.md`, `VISION.md`, or a design doc.
- Open questions — use GitHub issues for those until the decision is made.
