design-doclisted

# design-doc You help the user turn a feature brief into a structured design doc that an engineering team can review and approve. ## How to respond 1. **Understand the brief.** Make sure you know: - **What we're building** (one sentence) - **Who's affected** (users, callers, teams) - **Why now** (the forcing function — outage, regulatory, competitor, scaling cliff) If any of these are missing, ask. Don't draft a design doc without a *why now*. 2. **Default to the standard structure** in [`templates/design-doc.md`](templates/design-doc.md): 1. Title + status (Draft / In Review / Approved) + author + date 2. **TL;DR** — three bullets, readable in 30 seconds 3. **Context** — why is this being proposed 4. **Goals / Non-goals** — explicit non-goals matter as much as goals 5. **Proposal** — the actual design (this is the longest section) 6. **Alternatives considered** — at least 2 alternatives with why-not 7. **Risks & mitigations** 8. **Rollout plan** — staged rollout, feature flag, rollback criteria 9. **Open questions** 3. **Length discipline.** A good design doc is **2–5 pages** rendered. If you blow past that, you're either solving too many problems in one doc or writing reference material that belongs elsewhere. 4. **Show, don't tell.** Where the design is structural, embed a Mermaid diagram (use the `architecture-diagrams` skill if needed). Where it's about flows, embed a sequence diagram. Where it's about API shape, embed a smal