adr git:20260703.c5a2b92A

Immutable. This exact content is served forever at /api/v1/blob/2698dff50067f4d3.

---
name: adr
description: Use when a design decision is made that is expensive to reverse, affects multiple components, or rejects a plausible alternative — record it as an Architecture Decision Record under docs/hydraia/adr/. Also use to supersede an old decision. Not for trivial choices.
---

# 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.