--- name: adr-compliance description: Use when deeply validating an ADR's format, approval chain, linkage to standards, or deciding the correct ADR status version: 1.0.0 owner: platform-governance tier: full source: .enterprise/governance/agent-skills/adr-compliance/SKILL.md quick: .enterprise/governance/agent-skills/adr-compliance/SKILL-QUICK.md portable: true license: Apache-2.0 --- # ADR Compliance ## When to use Use this skill when: - creating a new ADR - reviewing a submitted ADR for approval - validating that a change requiring an ADR has one - checking that an ADR correctly references affected standards - generating an ADR draft on behalf of a human author --- ## 1. When an ADR is Required An ADR MUST be created for: - AD-01: Architectural changes (new patterns, new boundaries, structural refactoring) - AD-02: Technology or framework additions (new dependency, new platform, new language) - AD-03: Breaking changes to APIs, events, or data contracts - AD-04: Security posture changes (auth method, encryption change, new exposure) - AD-05: Deviation from any active standard or policy - AD-06: Data migration or schema evolution affecting production data - AD-07: Performance-impacting changes (new caching strategy, query changes on hot paths) - AD-08: Governance or standards modifications If uncertain whether an ADR is needed: create one. The cost is low; the cost of undocumented decisions is high. --- ## 2. ADR File Naming & Location - AD-09: ADRs MUST be stored under `.specs/decisions/`. - AD-10: File name MUST follow: `ADR-XXXX-.md` - Example: `ADR-0012-adopt-event-sourcing-for-audit-trail.md` - AD-11: XXXX is a zero-padded sequential number. - AD-12: Numbers MUST NOT be reused, even if an ADR is deprecated or superseded. --- ## 3. Required Sections & Content Every ADR MUST contain all of the following sections: ### 3.1 Header ``` # ADR-XXXX — [Short Title] **Status:** Draft | Proposed | Accepted | Deprecated | Superseded by ADR-XXXX **Date:** YYYY-MM-DD **Authors:** [name(s)] **Approved by:** [name(s)] (required before Accepted status) ``` ### 3.2 Context - AD-13: Describe the situation, problem, or requirement that necessitates a decision. - AD-14: Reference the relevant standards, constraints, or business drivers. - AD-15: Context MUST be factual — not the decision itself. ### 3.3 Decision - AD-16: State the decision clearly and unambiguously. - AD-17: Use active voice: "We will adopt...", "The system will use...", "This service MUST...". - AD-18: The decision MUST be actionable — agents and engineers must be able to implement from it. ### 3.4 Alternatives Considered - AD-19: At least one alternative MUST be documented. - AD-20: Each alternative MUST include: description, pros, cons, and reason it was not chosen. - AD-21: "Do nothing" is always a valid alternative and MUST be evaluated. ### 3.5 Consequences - AD-22: List positive consequences (benefits, improvements). - AD-23: List negative consequences (trade-offs, risks, debt introduced). - AD-24: Mitigation plan for identified risks MUST be included. - AD-25: Impact on existing components, services, or standards MUST be described. ### 3.6 Affected Standards - AD-26: List every spec, standard, or policy this ADR modifies, deviates from, or supersedes. - AD-27: Include the specific section or rule ID that is affected. - AD-28: If this ADR introduces a new exception, state the exception scope and expiry date. --- ## 4. Status Lifecycle ``` Draft → Proposed → Accepted ↘ Deprecated ↘ Superseded by ADR-XXXX ``` - AD-29: `Draft` — work in progress, not yet reviewable. - AD-30: `Proposed` — ready for review; must not be implemented until `Accepted`. - AD-31: `Accepted` — approved by authorized owner; implementation may proceed. - AD-32: `Deprecated` — decision is no longer in effect; superseding context must be explained. - AD-33: `Superseded` — replaced by a newer ADR; reference to successor MUST be included. - AD-34: Implementation MUST NOT begin until status is `Accepted`. --- ## 5. Approval Requirements - AD-35: ADRs affecting architecture require approval from: Platform Architecture Owner or Staff Engineer. - AD-36: ADRs affecting security posture require approval from: Security Owner. - AD-37: ADRs affecting governance or standards require approval from: Engineering Leadership. - AD-38: ADRs for local service deviations (no cross-team impact) require approval from: Tech Lead of the affected team. - AD-39: Self-approval is forbidden — the author MUST NOT be the sole approver. --- ## 6. ADR Immutability Rules - AD-40: Accepted ADRs MUST NOT be edited to change the decision retroactively. - AD-41: If a decision changes, a new ADR MUST be created with `Supersedes: ADR-XXXX`. - AD-42: Corrections to typos or formatting are allowed without creating a new ADR. - AD-43: Context updates that do not change the decision are allowed with a changelog note in the ADR. --- ## 7. ADR Draft Template When generating an ADR draft, use this structure: ```markdown # ADR-XXXX — [Short Title] **Status:** Draft **Date:** YYYY-MM-DD **Authors:** [name] **Approved by:** — --- ## Context [Describe the problem or situation requiring a decision.] ## Decision [State clearly what has been decided.] ## Alternatives Considered ### Option A — [Name] - **Description:** ... - **Pros:** ... - **Cons:** ... - **Rejected because:** ... ### Option B — Do Nothing - **Description:** Maintain current approach. - **Pros:** No disruption. - **Cons:** [Why this is insufficient.] - **Rejected because:** ... ## Consequences ### Positive - ... ### Negative / Trade-offs - ... ### Risks & Mitigations - **Risk:** ... **Mitigation:** ... ## Affected Standards - [Standard name] — [Section/rule affected] ``` --- ## Examples ✅ Good: ADR-0007 with all sections, alternatives, explicit risks, approved by Platform Architect. ✅ Good: ADR that supersedes ADR-0003 and clearly explains why the old decision is no longer valid. ❌ Bad: ADR with only Context and Decision sections — missing Alternatives and Consequences. ❌ Bad: ADR in `Accepted` status with no approver listed. ❌ Bad: Implementation proceeding while ADR is still in `Draft` status. ## Quick Mode For low-context activation, load `.enterprise/governance/agent-skills/adr-compliance/SKILL-QUICK.md` or `QUICK.md` first. Load this full skill for deep analysis, violation fixing, or formal review gates.