adrlisted

# ADR ## When to write one Write an ADR when the decision is **expensive to reverse**. The test: would undoing this in six months require a migration, a rewrite, or a contract negotiation? Then it needs a record. Do **not** write one for: library version bumps, naming, formatting, or anything a single pull request can undo. ## Location `docs/adr/NNNN-kebab-title.md`. Sequential, zero-padded, **never renumbered** — links rot otherwise. ## Template ```markdown # NNNN. <Title stated as the decision, not the problem> - Status: Proposed | Accepted | Superseded by NNNN - Date: YYYY-MM-DD - Deciders: <names or agent roles> ## Context <The forces. Facts and constraints only — no narrative, no history lesson. What makes this hard? What did we measure? What are we not allowed to change?> ## Decision <What we will do, active voice, present tense. "We will shard by tenant_id." Not "it was decided that sharding might be considered."> ## Consequences <What becomes easier. What becomes harder. What we now owe — the debt this creates. Include the ugly ones; the ADR is worthless if it only lists benefits.> ## Alternatives Considered <Each real option with the concrete, specific reason it lost.> ``` ## Worked example Two versions of the same Alternatives section: **Weak — unfalsifiable, tells a future reader nothing:** ```markdown ## Alternatives Considered - Sharding by user_id: not a good fit for our use case. - Read replicas: didn't scale well enough. - Bigger instance: too