jdanigo ADR — Architecture Decision Records (MADR-lite)
One file per decision: docs/hydraia/adr/NNNN-<slug>.md, zero-padded, monotonic (0001-..., 0002-...). Find the next number with ls docs/hydraia/adr/ | sort | tail -1.
When to write one (all it takes is ONE of these)
- Expensive to reverse (data store, auth model, hosting, framework).
- Affects multiple components or teams.
- A plausible alternative was seriously considered and rejected.
When NONE hold → no ADR. ADR spam buries the decisions that matter.
Template
# NNNN — <decision title>
**Status:** proposed | accepted | superseded by NNNN
**Date:** YYYY-MM-DD
## Context
<the forces: requirements, constraints, and any assumption made because
the human could not answer — stated as an assumption with its revisit
trigger>
## Decision
<what was decided, in one or two sentences, active voice>
## Alternatives considered
- <alternative> — rejected because <reason>
## Consequences
- Good: <what this buys>
- Bad: <what this costs — every decision costs something; empty is a smell>
Lifecycle rules
- Write at decision time (Phase 2 / greenfield step 5), commit with the spec.
- Supersede, never rewrite: a change of mind = NEW ADR + flip the old one's Status to
superseded by NNNN. History stays honest. - The Phase 2 spec references ADRs by number; reviewers check code against accepted ADRs.