designlisted

@.claude/shirabe-extensions/design.md @.claude/shirabe-extensions/design.local.md # Design Documents Design documents capture HOW to build something -- the technical approach, trade-offs considered, and architecture chosen. They complement PRDs (which capture WHAT and WHY) and are the input for /plan (which breaks designs into issues). **Writing style:** Read `skills/writing-style/SKILL.md` for guidance. ## Artifact Lifecycle **Lifecycle:** Durable. Stays in `docs/designs/` after completion. DESIGN is durable because the architectural decisions captured at DESIGN-Accepted time are the audit trail of how the implementation was chosen. Future readers asking why a particular architecture was selected need the DESIGN to remain in place; Current-state designs move to docs/designs/current/ but stay on disk. ## Structure ### Frontmatter Every design doc begins with YAML frontmatter: ```yaml --- status: Proposed problem: | 1 paragraph: what's broken or missing, who it affects, why now. decision: | 1 paragraph: chosen approach and key design elements. rationale: | 1 paragraph: why this approach, what trade-offs were weighed. --- ``` All four fields required. Use literal block scalars (`|`). Frontmatter status must match the Status section in the body -- agent workflows parse frontmatter to determine lifecycle state, so divergence causes silent errors. The frontmatter provides a self-contained summary so readers can understand the design without reading the full docume