What problem does it solve? Design documentation rots quickly: ADRs lose status tracking, code comments cite dead tickets, and docs drift from the structure they claim to follow. This Skill gives a repository one enforceable documentation framework — MADR-style ADRs with a generated status index, a rationale index behind # why: code pointers, a C4-levelled architecture doc, a root glossary, and Diátaxis-organised docs — plus the scripts and audit procedure that measure drift against it. ## Core Features & Use Cases - Adopt mode: Surveys an existing repository, asks the owner only the adoption decisions, scaffolds the manifest, ADR index, rationale areas, glossary, and CI checks, and records the adoption as an ADR. - Author mode: Applies the ADR trigger test (hard to reverse, surprising, real trade-off) and writes decisions as ADRs, rationale entries with # why: pointers, glossary terms, or C4 architecture changes. - Audit mode: Runs scripted Tier 1 checks (pointer resolution, ADR index drift, MADR sections, Diátaxis layout, glossary consistency) and guides Tier 2 cross-reference checks, producing an ephemeral gap report handed to planning. - Use Case: A maintainer says "audit the docs" before a milestone; the Skill runs scripts/audit.sh, clusters findings like dead citations and missing ADR sections, and hands a sized remediation backlog to the planning workflow without editing anything. ## Quick Start Ask the agent to adopt the design-docs documentation standard in this repository and scaffold the ADR, rationale, and Diátaxis structure.
