# Architecture Decision (AD) Truth document — with the one sanctioned dated tail. Use for: the standing decision on one architectural **subject** — a system shape, a contract, a substrate choice. Lives in `docs/architecture/decisions/`. The body always states the current decision and its current reasoning. When the decision moves, rewrite the affected sections to what is now true, bump `last-updated`, and append the revision to the **Decision Changelog** — the journey lives in that tail, never in the body. Head is truth; tail is provenance. ### One subject per AD The unit is the subject, not the individual call. "The persistence layer", "auth", "the design-skill architecture" are subjects; every decision, reversal, and re-decision on a subject lands in that subject's one AD, however many times it moves. Write a second AD only when a genuinely separate subject emerges — never to record a revision of an existing one. ### When to write an AD Write an AD when **all three** apply: 1. The decision is architectural — affects system shape, contracts, or substrate choice, not internal implementation 2. Alternatives were genuinely considered and rejected 3. Future maintainers will ask "why is it this way?" Don't write an AD for: - Standing principles or style preferences (those are stances, not decisions — put them in `docs/architecture/`) - Routine implementation choices with no rejected alternatives - Anything you'd be happy reversing without ceremony ### Lifecycle `Proposed` → `Accepted` → `Deprecated` Frontmatter `status:` is the single lifecycle source of truth. An AD stays `Accepted` for as long as its subject is live — revisions rewrite the body and never change the status, and there is **no `Superseded` state**: supersession is an edit plus a changelog entry, not a new document. Set `Deprecated` only when the subject itself is retired (the component is gone, the contract no longer exists); state where the replacement lives, if any. ### Naming `AD-NNN-short-title.md` — three-digit zero-padded number, kebab-case subject. Numbers are assigned sequentially across the project and never reused. ### Structure Three sections are required: **Decision**, **Context**, **Consequences** — plus the **Decision Changelog** once the AD has been revised at least once. Everything else is optional — include only when warranted. Decision-first: readers should see the answer in the first paragraph. ### Template ```markdown --- title: "AD-NNN: Short title in sentence case" status: Accepted # Proposed | Accepted | Deprecated created: YYYY-MM-DD last-updated: YYYY-MM-DD # bump on every revision decision-owner: Name reviewers: [] # optional tags: [ad] --- # AD-NNN: Short Title ## Decision [One paragraph, active voice. "We will…" Lead with the answer — the current answer, whatever the journey was.] ## Context [The forces in play. What is the problem? Why does it need a decision? Technical, political, social, and project-local pressures — stated as present-tense forces, not as a history of the subject.] ## Consequences **Positive:** - [What becomes easier] **Negative:** - [What becomes harder, what we accept reluctantly] **Risks:** - [Second-order effects you can already see, with mitigations if known] ## Decision Drivers [Hard non-negotiables vs. strong levers. Include when alternatives exist and the criteria aren't self-evident from Context.] ## Options Considered | Option | Pros | Cons | Outcome | | ------------ | ---- | ---- | --------------------- | | **Option A** | … | … | **CHOSEN** | | Option B | … | … | Eliminated — [reason] | ## Deep Comparison [Honest framing of the strongest alternative(s). Include when the table doesn't make the reasoning obvious. State the *real* reason each was rejected — not a strawman.] ## Architecture in Detail [Diagrams, code shape, layer responsibilities. Include when the decision implies non-trivial structure that readers need to understand alongside the *why*. Execution belongs in a plan doc (`docs/history/plans/`) — link to it, don't embed an implementation plan here.] ## Open Questions 1. **[Question]** — _Default_: [stated default until resolved]. ## References - [External link or cross-reference] ## Decision Changelog - YYYY-MM-DD — [What changed] because [trigger]. Implemented by [plan link]. (Previously: [old choice].) - YYYY-MM-DD — Initial decision accepted. Implemented by [plan link]. ``` ### Rules - **One subject per AD; all its revisions stay inside it.** Two genuinely different subjects means two ADs — a revision of an existing subject never does. - **The body is always the current truth.** Rewrite affected sections on every revision; never leave a superseded choice narrated in the body — the Decision Changelog carries the journey, with each entry naming the old choice and the trigger. - Decision-first. The first paragraph after the heading is the answer; readers should not need to scroll. - **Consequences lists positives, negatives, AND risks.** Pros-only Consequences is the genre's classic failure — one AD's honest resulting context is the input context for the next. - **Options Considered keeps every genuinely rejected alternative with the real reason.** Informed rejections are the most expensive knowledge to lose; a rejection made with strong prior art in view says so explicitly. - **Keep it short — one to two pages.** Long decision docs don't get updated. How-it-works detail belongs in the owning feature doc; execution in a plan. Link, don't embed. - No section numbering (`§5.1.1`). Use markdown headings only — inserting a section shouldn't renumber everything. - Frontmatter `status` is the single source of truth for lifecycle. Don't also write "Status: Accepted" in the body. - The Decision Changelog is append-only, newest first. Typo and formatting fixes don't get entries.