# Design: {FEATURE_NAME}

**Phase**: Design  
**Date**: {DATE}  
**Iteration**: {ITERATION_ID}

<design_prerequisites>
  <verify>Feature requirements understood from feature-init.md</verify>
  <verify>Technical constraints identified</verify>
  <verify>Integration points mapped</verify>
  <verify>User scenarios and acceptance criteria clear</verify>
  <verify>Performance and security requirements understood</verify>
</design_prerequisites>

## Overview

[2-3 sentences describing the technical approach]

## Architecture

```
[Component Diagram]
┌─────────────┐     ┌─────────────┐
│ Component A │────▶│ Component B │
└─────────────┘     └─────────────┘
       │                    │
       ▼                    ▼
┌─────────────┐     ┌─────────────┐
│ Component C │     │ Component D │
└─────────────┘     └─────────────┘
```

## Components

### {Component A}
**Purpose**: [What it does]  
**Inputs**: [What it receives]  
**Outputs**: [What it produces]  
**Key Logic**: [Core algorithm/approach]

### {Component B}
[Repeat structure for each component]

<component_validation>
  <verify>All components have clear purposes defined</verify>
  <verify>Input and output contracts specified for each component</verify>
  <verify>Key algorithms and logic documented</verify>
  <verify>Dependencies between components mapped</verify>
  <verify>Error handling approach defined per component</verify>
</component_validation>

## Primary Workflows

### Workflow 1: [Name]
1. [Step 1]
2. [Step 2]
3. [Step 3]
→ Result: [Outcome]

### Workflow 2: [Name]
1. [Step 1]
2. [Step 2]
→ Result: [Outcome]

<workflow_validation>
  <verify>All primary user scenarios have workflows defined</verify>
  <verify>Each workflow has clear steps and expected outcomes</verify>
  <verify>Happy path workflows documented</verify>
  <verify>Error/exception workflows included</verify>
  <verify>Workflow dependencies and prerequisites noted</verify>
</workflow_validation>

## Edge Cases and Error Handling

### Input Edge Cases
- **Missing data**: [How handled]
- **Invalid data**: [How handled]
- **Boundary conditions**: [How handled]

### System Edge Cases
- **Concurrent access**: [How handled]
- **Resource limits**: [How handled]
- **Partial failures**: [How handled]

### Error Recovery
- **Validation errors**: [Recovery approach]
- **System errors**: [Recovery approach]
- **External failures**: [Recovery approach]

<edge_case_validation>
  <input_cases>
    <verify>Missing data handling strategy defined</verify>
    <verify>Invalid data validation and rejection approach clear</verify>
    <verify>Boundary conditions (min/max values) addressed</verify>
  </input_cases>
  <system_cases>
    <verify>Concurrency conflicts resolution strategy defined</verify>
    <verify>Resource exhaustion scenarios handled</verify>
    <verify>Partial failure recovery mechanisms in place</verify>
  </system_cases>
  <recovery_approach>
    <verify>User-friendly error messages planned</verify>
    <verify>Graceful degradation strategies defined</verify>
    <verify>Rollback/compensation logic documented</verify>
  </recovery_approach>
</edge_case_validation>

## Data Structures

### Primary Data
```
{DataStructure1}:
  - field1: [type/description]
  - field2: [type/description]
  - field3: [type/description]
```

### Supporting Data
```
{DataStructure2}:
  - field1: [type/description]
  - field2: [type/description]
```

## Interface Design

### Operations
- **Create**: [Input] → [Output]
- **Read**: [Input] → [Output]
- **Update**: [Input] → [Output]
- **Delete**: [Input] → [Output]

### Data Flow Example
```
Input:
  - field1: value
  - field2: value

Output:
  - result: value
  - status: value
```

## Verification Strategy

### Component Testing
- **Coverage**: All public interfaces
- **Focus**: Logic correctness
- **Key scenarios**: Normal flow, edge cases, errors

### Integration Testing
- **Coverage**: Component interactions
- **Focus**: Data flow and contracts
- **Key scenarios**: Full workflows, error propagation

### Performance Targets
- Response time: [Target]
- Throughput: [Target]
- Resource usage: [Limits]

## Quality Attributes

### Security
- Input validation approach
- Access control pattern
- Data protection method

### Performance
- Expected load: [Volume/frequency]
- Optimization approach: [Strategy]
- Scalability considerations

## Key Decisions

| Question | Decision | Rationale |
|----------|----------|-----------|
| [Design choice 1] | [Selected option] | [Why this choice] |
| [Design choice 2] | [Selected option] | [Why this choice] |

## Risks

| Risk | Mitigation |
|------|------------|
| [Technical risk] | [How we'll handle it] |
| [Implementation risk] | [How we'll handle it] |

<design_completeness>
  <architecture>
    <verify>All components defined with clear responsibilities</verify>
    <verify>Component interactions and dependencies documented</verify>
    <verify>Data flow between components mapped</verify>
    <verify>Integration points with existing system identified</verify>
  </architecture>
  <quality_attributes>
    <verify>Security considerations addressed (auth, validation, data protection)</verify>
    <verify>Performance targets and optimization strategies defined</verify>
    <verify>Scalability approach documented</verify>
    <verify>Error handling and recovery strategies comprehensive</verify>
  </quality_attributes>
  <testability>
    <verify>Testing strategy covers all components</verify>
    <verify>Test scenarios include edge cases</verify>
    <verify>Performance benchmarks defined</verify>
    <verify>Integration test approach clear</verify>
  </testability>
  <decisions_and_risks>
    <verify>All major design decisions documented with rationale</verify>
    <verify>Technical and implementation risks identified</verify>
    <verify>Mitigation strategies defined for each risk</verify>
    <verify>Trade-offs explicitly acknowledged</verify>
  </decisions_and_risks>
</design_completeness>

---
Next: `/feature:plan-testing`