writing-design

Writing Design

Before starting, read the approved specs/{feature_name}/requirements.md, then read design-prompt.md and design-templete.md. If Requirements has not received explicit user approval, stop and request completion of that approval first.

Constraints:

• The model MUST create a 'specs/{feature_name}/design.md' file if it doesn't already exist
• The model MUST identify areas where research is needed based on the feature requirements
• The model MUST conduct research and build up context in the conversation thread
• The model SHOULD NOT create separate research files, but instead use the research as context for the design and implementation plan
• The model MUST summarize key findings that will inform the feature design
• The model SHOULD cite sources and include relevant links in the conversation
• The model MUST create a detailed design document at 'specs/{feature_name}/design.md'
• The model MUST incorporate research findings directly into the design process
• The model SHOULD include diagrams or visual representations when appropriate (use Mermaid for diagrams if applicable)
• The model MUST ensure the design addresses all feature requirements identified during the clarification process
• The model SHOULD highlight design decisions and their rationales
• The model MAY ask the user for input on specific technical decisions during the design process
• After updating the design document, the model MUST ask the user "Does the design look good? If so, we can move on to the implementation plan." using the AskUserQuestion tool (Claude Code).
• The AskUserQuestion tool MUST be used; set metadata.source to the exact string 'spec-design-review'
• The model MUST make modifications to the design document if the user requests changes or does not explicitly approve
• The model MUST ask for explicit approval after every iteration of edits to the design document
• The model MUST NOT proceed to the implementation plan until receiving clear approval (such as "yes", "approved", "looks good", etc.)
• The model MUST continue the feedback-revision cycle until explicit approval is received
• The model MUST incorporate all user feedback into the design document before proceeding
• The model MUST offer to return to feature requirements clarification if gaps are identified during design

Research Limitations

If the model cannot access needed information:

• The model SHOULD document what information is missing
• The model SHOULD suggest alternative approaches based on available information
• The model MAY ask the user to provide additional context or documentation
• The model SHOULD continue with available information rather than blocking progress

Design Complexity

If the design becomes too complex or unwieldy:

• The model SHOULD suggest breaking it down into smaller, more manageable components
• The model SHOULD focus on core functionality first
• The model MAY suggest a phased approach to implementation
• The model SHOULD return to requirements clarification to prioritize features if needed