Design

• One question at a time. Ask one question, wait for the answer, then proceed. Use AskUserQuestion for simple choices; use plain text for code-heavy questions.
• Exception: code-heavy questions. When a question involves code snippets, API shapes, or type signatures, present it in plain text instead of AskUserQuestion. The tool's preview feature cannot reliably display full code blocks.
• Start with the hardest question. Identify the central design tension (e.g., API shape, data flow, ownership model) and explore it first. Easier decisions fall into place once the hard ones are resolved.
• Present concrete alternatives with code. Show what each option looks like in practice, not just in the abstract. Name the tradeoffs.
• Follow the user's curiosity. When the user pushes back or wants to probe deeper, that's signal — the design is getting stronger. Don't rush to close questions.
• Let decisions compound. Each resolved question constrains the next. Revisit earlier decisions if a later exploration reveals a better path.
• Exit condition. Move to section proposal when the major design decisions are resolved — you should be able to write the Architecture section without open questions. If you're unsure, ask the user if they're ready to move to section proposals.

4. Propose in sections

Present a summary of the following sections to the user, one by one. After each, ask for any corrections before proceeding.

Expect iteration. Review feedback on any section may surface new design questions that weren't visible during initial exploration. When this happens, return to "Explore the design space" rather than trying to resolve it inline during the review loop.

Present every section to the user for discussion — if a section is not relevant, explain why and confirm with the user before omitting it from the document.

Canonical sections:

• Overview / Problem Statement
• Requirements Summary
• Out of Scope
• Architecture
• Technology Choices
• Key Design Decisions
• Security Considerations
• Testing Strategy
• Monitoring Strategy
• Deployment Strategy
• Project-specific sections as needed

5. Confirm output location

• Propose the most relevant .ai-dev directory
• Confirm with the user before writing
• File naming: <topic>-design.md

6. Write and review

STOP: You must use /writing-docs to write the design doc and manage the review loop.

Ensure the following frontmatter is included:

---