/create_design

Create Design

Quick design generation with AI-driven creation and review cycle.

Initial Setup

Respond with:

I'm ready to help create your technical design.

I'll read your requirements from spec/requirements.md first.

Please tell me your tech stack preferences. You can be specific (e.g., 'Python, FastAPI, SQLite, Jinja2') or general (e.g., 'modern web stack') or just say 'you decide'.

Wait for user input.

Workflow

1. Read spec/requirements.md FULLY
2. Receive user's tech preferences
3. Fill in gaps with reasonable decisions based on:
   • What user specified
   • Requirements from requirements.md
   • Modern best practices
   • Project complexity and scope
4. Generate complete design document at spec/design.md
5. Be explicit about decisions made: "Based on your input, I made these decisions: [list with rationale]"
6. Present design with clear summary of tech choices
7. Ask: "Does this look good, or would you like me to make adjustments?"
8. If adjustments needed: make changes and repeat step 6-7
9. Guide toward completion (AI should signal when things look complete)

Guidelines

• Listen to user's tech preferences (specific or vague)
• Fill gaps intelligently - don't ask questions, make decisions
• Be explicit about what decisions were made and WHY
• Match complexity to project scope - don't over-engineer
• If no UI framework mentioned but requirements need UI, choose appropriate one
• If no testing preference mentioned, include appropriate testing strategy
• Align with requirements: every design decision should trace back to requirements
• Include concrete file/folder structures
• Design for both happy path and error cases
• AI should guide conversation toward wrap-up after 2-3 adjustment rounds

Chat Output Format

After generating design.md:

I've created a design document at spec/design.md.

Based on your input, I made these decisions:
- [Decision 1 with rationale - e.g., "React 18 with TypeScript for type safety and modern features"]
- [Decision 2 with rationale - e.g., "localStorage for data persistence since requirements don't need server sync"]
- [Decision 3 with rationale - e.g., "Vitest + React Testing Library for component testing (matches Vite build tool)"]

The design includes:
- Complete tech stack with rationale
- Component breakdown with responsibilities
- Data model and [UI structure if applicable]
- Key user flows and interactions
- File structure and testing strategy

Does this look good, or would you like me to make adjustments?

After adjustments (if needed):

I've updated spec/design.md with your feedback.

Changes made:
- [Change 1]
- [Change 2]

Does this look good now, or would you like further adjustments?

File Output Format

Create spec/design.md:

# Design: [Project Name]

## Design Overview
[2-3 sentences describing the technical approach and key architectural decisions]

## Tech Stack

### Languages & Frameworks
- **Language**: [e.g., JavaScript/TypeScript]
- **Framework**: [e.g., React 18]
- **Build Tool**: [e.g., Vite]
- **Styling**: [e.g., Tailwind CSS]

### Data & State
- **Data Storage**: [e.g., localStorage, PostgreSQL, MongoDB]
- **State Management**: [e.g., React Context, Redux, Zustand]
- **Data Format**: [e.g., JSON, structured data model]

### Dependencies
- [Library 1]: [Purpose]
- [Library 2]: [Purpose]

**Rationale**: [Why this tech stack? How does it fit the requirements?]

## System Architecture

### High-Level Architecture

[Diagram or description of system layers]

Example: ┌─────────────────────────────┐ │ Presentation Layer │ ← UI Components ├─────────────────────────────┤ │ Business Logic Layer │ ← State Management ├─────────────────────────────┤ │ Data Layer │ ← Storage/API └─────────────────────────────┘

### Component Breakdown

#### Component: [Name]
**Purpose**: [What this component does]  
**Location**: `src/components/ComponentName.tsx`  
**Responsibilities**:
- [Responsibility 1]
- [Responsibility 2]

**Props/Interface**:
```typescript
interface ComponentProps {
  prop1: string;
  prop2: number;
  onAction: () => void;
}

State:

Data Model

Entity: [EntityName]

interface EntityName {
  id: string;
  field1: string;
  field2: number;
  field3: Date;
}

Purpose: [What this represents]
Relationships: [How it relates to other entities]

User Interface Design

Screen: [ScreenName]

Purpose: [What user accomplishes here]
Layout:

┌─────────────────────────┐
│  Header                 │
├─────────────────────────┤
│  Main Content           │
│  - Element 1            │
│  - Element 2            │
├─────────────────────────┤
│  Footer/Actions         │
└─────────────────────────┘

Key Elements:

• [Element 1]: [Purpose and behavior]
• [Element 2]: [Purpose and behavior]

User Interactions:

• [Action 1] → [Result]
• [Action 2] → [Result]

Key Interactions & Flows

Flow: [FlowName]

Scenario: [User story this implements]

1. User [action]
2. System [response]
3. System [next step]
4. User sees [result]

Error Handling:

• If [error condition] → [behavior]
• If [error condition] → [behavior]

File Structure

project-root/
├── src/
│   ├── components/
│   │   ├── ComponentA.tsx
│   │   └── ComponentB.tsx
│   ├── hooks/
│   │   └── useCustomHook.ts
│   ├── utils/
│   │   └── helpers.ts
│   ├── types/
│   │   └── index.ts
│   ├── App.tsx
│   └── main.tsx
├── spec/
│   ├── requirements.md
│   └── design.md
├── package.json
└── README.md

Design Decisions & Tradeoffs

Decision: [DecisionName]

Choice: [What we decided]
Alternatives Considered: [What else we could do]
Rationale: [Why we chose this]
Tradeoffs: [What we gain/lose]

Non-Functional Considerations

Performance

• [Performance approach, e.g., "Lazy load components"]
• [Optimization strategy, e.g., "Memoize expensive calculations"]

Scalability

• [How design handles growth]
• [What needs to change if requirements scale]

Accessibility

• [Accessibility approach, e.g., "ARIA labels on all interactive elements"]
• [Keyboard navigation strategy]

Error Handling

• [Error handling strategy]
• [User feedback approach]

Testing Strategy

Philosophy: Every task must be verified before moving to the next. Testing is incremental and continuous.

Testing Tools & Framework

• Testing Framework: [e.g., Jest, pytest, Vitest, etc.]
• Testing Library: [e.g., React Testing Library, unittest, etc.]
• Test Runner Command: [e.g., npm test, pytest, etc.]
• Coverage Tool (if applicable): [e.g., Jest coverage, coverage.py]

Verification Approach for Each Task Type

Code/Logic Tasks

• Verification Method: Automated tests
• When to Test: [After each task / TDD / as you go]
• What to Test:
  • Function behavior with valid inputs
  • Edge cases and error handling
  • Integration with other components

UI/Component Tasks

• Verification Method: [Automated tests + manual verification / manual only]
• Automated Tests: Component rendering, props, interactions
• Manual Verification: Visual appearance, responsiveness, UX flow

Configuration/Setup Tasks

• Verification Method: [e.g., "Run build command", "Run dev server"]
• Success Criteria: No errors, expected output

Test Writing Approach

[Describe when tests should be written:]

• Test-Driven Development (TDD): Write tests before implementation
• Test-After: Implement feature, then write tests
• Incremental: Write tests as you implement

Critical Testing Rules

1. Every task must have clear verification steps
2. Tests must pass before moving to next task
3. If tests fail repeatedly (3+ times), stop and reassess
4. Document any tasks that cannot be automated (manual verification)

Unit Tests

• What: Test individual components/functions in isolation
• Where: src/__tests__/ or alongside source files
• Key areas: [List critical functions to test]
• Run Command: [command to run unit tests]

Integration Tests

• What: Test component interactions and data flow
• Key flows: [List important user flows to test]
• Run Command: [command to run integration tests]

Manual Testing Scenarios

• What: UI/UX verification that requires human judgment
• Key scenarios: [List scenarios to manually verify]
• When: After completing each phase with UI changes

Development Approach

Phase Breakdown

[High-level phases - detailed breakdown happens in plan.md]

1. Phase 1: [e.g., "Setup & Core Structure"]
2. Phase 2: [e.g., "Data Layer"]
3. Phase 3: [e.g., "UI Components"]
4. Phase 4: [e.g., "Integration & Polish"]

Development Standards

• [Coding conventions]
• [Naming conventions]
• [Documentation requirements]

Open Questions

[Any remaining technical uncertainties - resolve before planning]

• [Question 1]
• [Question 2]

References

• Requirements: spec/requirements.md
• [Any relevant documentation or resources]