decision-recordslisted

# Decision Records An **Architecture Decision Record (ADR)** captures the *why* and *what we gave up* behind a design decision — the parts code and docs cannot carry. This skill covers where records live, when to write one, and the in-file structure. It applies to any project that wants its rationale to outlive the change. **The defining constraint:** an ADR records a *decision* — the alternatives it beat and the consequences it accepted — not a transcript of how the decision was reached. A decision without its rejected alternatives invites re-litigation. ## Layout and lifecycle Every record has two axes: - **Lifecycle** — its status, which changes over time: - **proposed** — not yet built (or only partly); the plan and open questions live here. - **accepted / implemented** — the decision shipped; the file describes shipped reality in the **present tense** and is kept current with what actually shipped (facts — paths, names, structure — not the decision itself). - **rejected** — considered and declined; keep it only while its rationale prevents a tempting, meaningful mistake. - **Class** — the *kind* of decision (feature, bug-fix, simplification, architecture, process, testing). Pick the class folder that matches. A record moves between lifecycle folders as its status changes; the move updates the status line and the body's form in the same change. ## When to write one Write (or update) an ADR when a change is **non-trivial**: it alters behavior, architecture, a