/design

Overview

Transform rough ideas into fully-formed designs through structured questioning and alternative exploration.

Core principles

• Ask questions to understand
• Explore alternatives
• Present design incrementally for validation.

Quick Reference

Phase	Key Activities	Tool Usage	Output
1. Understanding	Ask questions (one at a time)	AskUserQuestion for choices	Purpose, constraints, criteria
2. Exploration	Propose 2-3 approaches	AskUserQuestion for approach selection	Architecture options with trade-offs
3. Design Presentation	Present in 200-300 word sections	Open-ended questions	Complete design with validation
4. Design Documentation	Write design document	Skill(writing-clearly-and-concisely)	Design doc in plans/
5. Implementation Plan	Create implementation plan	Skill(writing-plans)	Detailed task breakdown

The Process

Copy this checklist to track progress:

Brainstorming Progress:
- [ ] Phase 1: Understanding (purpose, constraints, criteria gathered)
- [ ] Phase 2: Exploration (2-3 approaches proposed and evaluated)
- [ ] Phase 3: Design Presentation (design validated in sections)
- [ ] Phase 4: Design Documentation (design written to plans)
- [ ] Phase 5: Implementation Plan (plan written to plans)

Phase 1: Understanding

• Check current project state in working directory
• Ask ONE question at a time to refine the idea
• Gather: Purpose, constraints, success criteria
• Use AskUserQuestion tool when you have multiple choice options

Example using AskUserQuestion:

Question: "Where should the authentication data be stored?"
Options:
  - "Session storage" (clears on tab close, more secure)
  - "Local storage" (persists across sessions, more convenient)
  - "Cookies" (works with SSR, compatible with older approach)

Phase 2: Exploration

• Propose 2-3 different approaches
• For each: Core architecture, trade-offs, complexity assessment
• Ask your human partner which approach resonates
• Use AskUserQuestion tool to present approaches as structured choices

Example using AskUserQuestion:

Question: "Which architectural approach should we use?"
Options:
  - "Event-driven with message queue" (scalable, complex setup, eventual consistency)
  - "Direct API calls with retry logic" (simple, synchronous, easier to debug)
  - "Hybrid with background jobs" (balanced, moderate complexity, best of both)

Phase 3: Design Presentation

• Present in 200-300 word sections
• Cover: Architecture, components, data flow, error handling, testing
• Ask after each section: "Does this look right so far?" (open-ended)
• Use open-ended questions here to allow freeform feedback

Phase 4: Design Documentation

After design is validated, write it to a permanent document:

• File location: plans/YYYY-MM-DD-<feature-name>/design.md (use actual date and descriptive topic)
• Content: Capture the design as discussed and validated in Phase 3, organized into the sections that emerged from the conversation

Phase 5: Planning Handoff

Ask: "Ready to create the implementation plan?"

If your human partner confirms (any affirmative response) use the creating-a-plan skill to create an implementation plan.

Question Patterns

When to Use AskUserQuestion Tool

Use AskUserQuestion for:

• Phase 1: Clarifying questions with 2-4 clear options
• Phase 2: Architectural approach selection (2-3 alternatives)
• Any decision with distinct, mutually exclusive choices
• When options have clear trade-offs to explain

Benefits:

• Structured presentation of options with descriptions
• Clear trade-off visibility for partner
• Forces explicit choice (prevents vague "maybe both" responses)

When to Use Open-Ended Questions

Use open-ended questions for:

• Phase 3: Design validation ("Does this look right so far?")
• When you need detailed feedback or explanation
• When partner should describe their own requirements
• When structured options would limit creative input

Example decision flow:

• "What authentication method?" → Use AskUserQuestion (2-4 options)
• "Does this design handle your use case?" → Open-ended (validation)

When to Revisit Earlier Phases

digraph revisit_phases {
    rankdir=LR;
    "New constraint revealed?" [shape=diamond];
    "Partner questions approach?" [shape=diamond];
    "Requirements unclear?" [shape=diamond];
    "Return to Phase 1" [shape=box, style=filled, fillcolor="#ffcccc"];
    "Return to Phase 2" [shape=box, style=filled, fillcolor="#ffffcc"];
    "Continue forward" [shape=box, style=filled, fillcolor="#ccffcc"];

    "New constraint revealed?" -> "Return to Phase 1" [label="yes"];
    "New constraint revealed?" -> "Partner questions approach?" [label="no"];
    "Partner questions approach?" -> "Return to Phase 2" [label="yes"];
    "Partner questions approach?" -> "Requirements unclear?" [label="no"];
    "Requirements unclear?" -> "Return to Phase 1" [label="yes"];
    "Requirements unclear?" -> "Continue forward" [label="no"];
}

You can and should go backward when:

• Partner reveals new constraint during Phase 2 or 3 → Return to Phase 1
• Validation shows fundamental gap in requirements → Return to Phase 1
• Partner questions approach during Phase 3 → Return to Phase 2
• Something doesn't make sense → Go back and clarify

Don't force forward linearly when going backward would give better results.

Key Principles

Principle	Application
One question at a time	Phase 1: Single question per message, use AskUserQuestion for choices
Structured choices	Use AskUserQuestion tool for 2-4 options with trade-offs
YAGNI ruthlessly	Remove unnecessary features from all designs
Explore alternatives	Always propose 2-3 approaches before settling
Incremental validation	Present design in sections, validate each
Flexible progression	Go backward when needed - flexibility > rigidity