adr-writing

## When to Use - Use when: a decision is hard to reverse (database choice, auth strategy, API protocol) - Use when: a decision will affect multiple teams or future developers - Use when: "why did we do it this way?" will be asked in 6 months - Use when: two legitimate approaches were evaluated and one was chosen - Do NOT write an ADR for: minor implementation choices that are easy to change **Rule of thumb:** If you'd be embarrassed to explain the decision with no written record, write an ADR. --- ## ADR Format (MADR) Save as `docs/adr/NNNN-short-title.md` where NNNN is a zero-padded sequence. ```markdown # NNNN. [Short title describing the decision] **Status:** [Proposed | Accepted | Deprecated | Superseded by ADR-NNNN] **Date:** YYYY-MM-DD **Deciders:** [names or team] ## Context and Problem Statement [Describe the problem or context that forced a decision. 2–4 sentences. Include constraints, deadlines, or requirements that shaped the decision space.] ## Decision Drivers * [Key factor 1 — e.g., team expertise in X] * [Key factor 2 — e.g., must support 10k concurrent users] * [Key factor 3 — e.g., licensing constraints] ## Considered Options * Option A — [one-line description] * Option B — [one-line description] * Option C — [one-line description] ## Decision Outcome Chosen option: **Option A**, because [brief reason tying back to decision drivers]. ### Positive Consequences * [Consequence 1] * [Consequence 2] ### Negative Consequences / Trade-offs * [Trad...