Architecture Decision Records (Summary)
In one line: Preserve who decided what, why, for which scope and exact revision; keep accepted history traceable as the system changes.
ADRs record significant technical decisions, alternatives and consequences. Assess the effect, not the patch label. A small configuration change can alter permissions or business meaning; a routine compatible library patch need not reopen an architecture decision.
| Change effect | Decision treatment |
|---|---|
| New or changed technology profile, architecture pattern, data boundary, integration semantics or security policy | Record the decision with the accountable owner and affected acceptance evidence. |
| Changed business rule or term meaning | Obtain the designated business owner's approval; a technical ADR does not substitute for it. |
| Implementation-only correction preserving accepted intent and contracts | Link the issue/change and verification evidence; create an ADR only if a significant architectural decision changes. |
| Factual error in an accepted record | Approved, dated additive erratum preserving original history; changed decisions use supersession. |
The record identifies stable ID, status, source/revision, context, decision, alternatives, consequences, accountable decision-maker, contributors (including AI), approval evidence and any supersession relation. A generated draft is proposed, not accepted because an agent or reviewer wrote “Accepted.” Permission to implement is separate from merge, release and activation authority.
Changes after acceptance preserve the historical decision. A superseding ADR and the register link in both directions; serialize identifier allocation rather than assuming “highest number + 1” is safe across concurrent authors. Restrict publication to audience-approved material.
Evidence: scripts/check-adr-register.sh checks register structure and exact reference consistency when invoked on the intended register. Its fixture run in this kit's CI is not an assessment of an adopter's register, human approval, runtime behavior or legal compliance. Verify the installed project gate and preserve the decision evidence separately.
Full procedure: skill:s4u-adr; reference and format: Appendix G.