---
name: design-doc-template
description: Design document template for feature planning
user-invocable: false
---

## Your Task

Use this design document template to plan a new feature or system. Fill in each section with the specifics of your design, including requirements, architecture, and deployment plan.

# [Feature Name] Design Document

**Date:** YYYY-MM-DD
**Author:** [Your Name]
**Status:** Draft | In Review | Approved

---

## Overview

Brief description of what is being designed and why.

**Goal:** What problem does this solve?

**Non-Goals:** What is explicitly out of scope?

---

## Requirements

### Functional Requirements
- Requirement 1
- Requirement 2
- Requirement 3

### Non-Functional Requirements
- **Performance:** Target metrics
- **Security:** Security considerations
- **Scalability:** Scale requirements

### Success Criteria
- How will we measure success?
- What does "done" look like?

---

## Approach Comparison

| Approach | Pros | Cons | Complexity | Chosen |
|----------|------|------|------------|--------|
| Option 1 | Benefits | Drawbacks | Low/Med/High | ☐ |
| Option 2 | Benefits | Drawbacks | Low/Med/High | ☐ |
| Option 3 | Benefits | Drawbacks | Low/Med/High | ☑ |

**Decision:** Why this approach was chosen.

---

## Architecture

### System Overview

```
[Component A] → [Component B] → [Component C]
     ↓              ↓              ↓
  [Detail]       [Detail]      [Detail]
```

### Components

#### Component 1
- **Purpose:** What it does
- **Technology:** Implementation details
- **Interface:** How it communicates

#### Component 2
- **Purpose:** What it does
- **Technology:** Implementation details
- **Interface:** How it communicates

---

## Data Flow

1. **Step 1:** User action triggers...
2. **Step 2:** System processes...
3. **Step 3:** Response is...

### Data Models

```typescript
interface DataModel {
  field1: string;
  field2: number;
  field3: Date;
}
```

---

## Security & Privacy

- **Authentication:** How users are authenticated
- **Authorization:** Access control rules
- **Data Protection:** Encryption, PII handling
- **Compliance:** GDPR, SOC2, etc.

---

## Error Handling

| Error Scenario | Handling Strategy | User Experience |
|----------------|-------------------|-----------------|
| Network failure | Retry with backoff | "Reconnecting..." |
| Invalid input | Validation error | Error message + suggestion |
| Server error | Graceful degradation | Fallback functionality |

---

## Testing Strategy

### Unit Tests
- Component A tests
- Component B tests

### Integration Tests
- End-to-end flow
- Error scenarios

### Performance Tests
- Load testing
- Stress testing

---

## Deployment Plan

### Rollout Strategy
- **Phase 1:** Feature flag, 5% users
- **Phase 2:** 25% users
- **Phase 3:** 100% rollout

### Rollback Plan
- How to disable feature quickly
- Data migration reversal (if applicable)

### Monitoring
- **Metrics to track:** List key metrics
- **Alerts:** When to page on-call

---

## Implementation Timeline

| Phase | Tasks | Duration | Dependencies |
|-------|-------|----------|--------------|
| Phase 1 | Core functionality | 1 week | None |
| Phase 2 | Error handling | 3 days | Phase 1 |
| Phase 3 | Testing & docs | 2 days | Phase 2 |

**Total estimated time:** X weeks

---

## Open Questions

1. Question about implementation detail?
2. Question about requirements?
3. Question about dependencies?

---

## Appendix

### References
- Link to related documents
- API documentation
- Design inspiration

### Revision History
| Date | Author | Changes |
|------|--------|---------|
| YYYY-MM-DD | Name | Initial draft |
