Agent skill · magnus919
adr-authoring
Write, review, and maintain architecture decision records with clear context, alternatives, consequences, confirmation links, and lifecycle governance. Use when a consequential technical decision or its enforceable architectural constraint must remain understandable. Do not use for system-wide evolutionary architecture design, general observability, or operating a named test or CI tool.
What it needs
About 4k tokens when loaded.
What this skill does
ADR Authoring Architecture Decision Records for capturing design rationale. ADRs supply the temporal dimension — decisions over time — that structure-only views (C4) miss. ADR-to-Pyramid Mapping ADR State Pyramid Layer Path ----------- -------------- ------ Navigation index L1 (Summary) 01-summary/adr-index.md Active ADRs L2 (Analysis) 02-analysis/architecture-decisions/ADR-NNN.md Superseded ADRs L3 (Dossiers) 03-dossiers/adr-superseded.md Without ADRs, an agent sees a snapshot of the structure but cannot reconstruct the path that led to it. Active ADRs in L2 provide the decision rationale. Superseded ADRs in L3 preserve the history of rejected alternatives. ADR Lifecycle ADRs progress through six stages, each with a gate criterion: Stage Status Pyramid Layer Consumer ------- -------- -------------- ---------- Initiating proposed L2 (02-analysis/) Engineers evaluating Researching proposed L2 (02-analysis/) Engineers evaluating Evaluating proposed L2 (02-analysis/) Engineers deciding Implementing accepted L2 (02-analysis/) Implementers, reviewers Maintaining accepted L2 (02-analysis/) New team members, auditors Sunsetting deprecated/superseded L3 (03-dossiers/) Historians All live ADRs (proposed + accepted) stay in L2. Only superseded/deprecated ADRs move to L3. Proposed ADRs that are rejected should be moved to L3 with status rejected and a note on why. Alternative Lifecycle: AWS ADR Process AWS Prescriptive Guidance defines a complementary lifecycle with a structured review process for teams that prefer formal immutability over living documents. States: proposed → accepted rejected superseded Key difference: AWS treats ADRs as strictly immutable once accepted. Changing a decision requires a new ADR that supersedes the old one. The community ADR repo's teamwork advice prefers mutable living documents with date-stamped updates. Choose the model that fits your team's culture. AWS Review Process: 1. Proposal — any team member creates an ADR in proposed state. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills magnus919/adr-authoring