Architecture Decision Records¶
An ADR is a short document that records one important decision: the context, what we chose, what it costs us, and what we rejected. Think of it as the project's memory. Six months from now, "why is it like this?" has a written answer instead of a guess.
When to write one¶
Write an ADR when a decision is hard to undo (a "one-way door") or when the two maintainers disagreed and settled it. Examples: storage format, ID and hashing schemes, public API shape, a new core dependency, a change to the statistics contract.
Do not write one for easily reversible choices (CLI colours, internal helper names).
How¶
- Copy the template to
NNNN-short-title.mdwith the next number. - Open a pull request with status Proposed. Discuss in the PR.
- On merge, set the status to Accepted.
- ADRs are never edited after acceptance, except for their status. To change a decision, write a new ADR and mark the old one Superseded by ADR-NNNN.
Index¶
| ADR | Title | Status |
|---|---|---|
| 0001 | SQLite is the default store | Accepted |
| 0002 | Thin edges, thick core | Accepted |
| 0003 | Binary criteria only | Accepted |
| 0004 | Protocols are the contract; helper base classes are optional | Accepted |
| 0005 | Package layout and enforced layer rules | Accepted |
| 0006 | Content-addressed IDs and immutable hash-based splits | Accepted |
| 0007 | Build the statistics core and storage as parallel tracks | Accepted |
| 0008 | Zensical for the documentation site | Accepted |
| 0009 | Lean runtime: NumPy and the standard library, no SciPy | Accepted |
| 0010 | Data backbone identities, split sets and synchronous stores | Proposed |
| 0011 | Explicit offline report assumptions and adjudication | Proposed |
| 0012 | Rich at the CLI boundary | Proposed |