What problem does it solve? Teams lose the reasoning behind significant technical decisions as people leave and time passes, leaving future engineers asking "why was it built this way?" with no answer. This Skill applies Michael Nygard's Architecture Decision Records (ADRs) to capture decisions, their context, and their consequences as lightweight, version-controlled Markdown documents. ## Core Features & Use Cases - Nygard's Classic Format: Structures ADRs with Title, Status, Context, Decision, and Consequences fields, plus optional alternatives and stakeholder sections. - Status Lifecycle Management: Guides Proposed, Accepted, Deprecated, and Superseded-by transitions while keeping accepted ADRs immutable to preserve decision history. - Significance Heuristics: Provides concrete rules for when a decision warrants an ADR versus when it does not, plus variants like MADR, Y-Statements, and lightweight ADRs. - Use Case: When choosing PostgreSQL over MySQL for a new service, draft a Proposed ADR in docs/adr/, let the team comment on it, then mark it Accepted so future joiners understand the trade-offs six months later. ## Quick Start Ask Claude to draft an ADR for a significant technical decision you are currently making, including the context, alternatives considered, and honest consequences.
