architecture-docslisted

# Architecture Docs Skill ## Trigger - `/architecture-docs` — full regeneration. - `/architecture-docs <subsystem>` — refresh a single subsystem file; skips Phases 1, 3, 4, 5, 6, 8, 9. - `/architecture-docs --verify-idempotent` — run the skill twice on an unchanged tree and `git diff --stat docs/architecture/`. Non-empty diff = the skill is not idempotent and produced non-deterministic output. ## Purpose Produce a regenerable, citation-anchored set of architecture documents under `/docs/architecture/` that capture **what the system is and why**, grounded in code and git history — not in `.designs/` (design documents can be wrong and have been wrong). Future designs and reviews use these docs as the truth source for "how does this codebase already handle this concern?" so an author cannot propose a fix that diverges from an established idiom without naming the divergence and justifying it. ## Why this skill exists (read before running) Design reviews routinely fail in a specific way: an author synthesizes an "options considered" section from the problem statement without first checking whether the codebase already has a canonical idiom for the problem shape. When no document aggregates the existing idiom across its call sites, the author has no efficient way to discover it, and reviewers have no efficient way to challenge deviations from it. Designs then ship that quietly weaken invariants the codebase was previously enforcing through combined mechanisms. The fix