/design-documentation

name: design-documentation
description: Transform approved requirements into comprehensive technical designs. Define system architecture, component interactions, data models, and interfaces to create a blueprint for implementation.
license: MIT
compatibility: Claude Code, Cursor, VS Code, Windsurf
metadata:
  category: methodology
  complexity: intermediate
  author: Kiro Team
  version: "1.0.0"

Design Documentation

Create technical blueprints that bridge requirements and implementation. This skill teaches how to document architecture decisions, component design, and system interactions.

When to Use This Skill

Use design documentation when:

• Requirements phase is complete and approved
• You need to plan technical implementation
• Multiple developers will work on the feature
• Architecture decisions need documentation
• The feature involves complex integrations

Design Document Structure

Standard Template

# Design Document: [Feature Name]

## Overview
[High-level summary of the feature and approach]

## Architecture
[System architecture and component overview]

## Components and Interfaces
[Detailed component descriptions and interactions]

## Data Models
[Data structures and relationships]

## Error Handling
[Error scenarios and response strategies]

## Testing Strategy
[Testing approach and quality assurance]

Step-by-Step Process

Step 1: Requirements Analysis

Before designing, ensure you understand:

• All functional requirements
• Non-functional requirements (performance, security, scalability)
• Constraints (technology stack, timeline, resources)
• Integration points with existing systems

**Analysis Questions:**

• What does the system need to do?
• What are the performance expectations?
• What existing code/systems does this touch?
• What are the security requirements?
• What could go wrong?

Step 2: Research and Context Building

Identify areas needing research:

• Technology choices and alternatives
• Third-party integrations and APIs
• Best practices for similar systems
• Security and compliance considerations

**Research Documentation:**

## Research Findings

### [Topic]
**Sources:** [Links/references]
**Key Insights:**
- [Finding 1]
- [Finding 2]
**Impact on Design:** [How this affects our approach]

Step 3: Define System Architecture

Document the high-level structure:

## Architecture

### System Overview
[How the overall system works]

### Component Architecture
[Major components and their responsibilities]

### Data Flow
[How information moves through the system]

### Technology Decisions
[Key technology choices and rationale]

**Architecture Diagram (Mermaid):**

graph TD
    A[Client] --> B[API Gateway]
    B --> C[Auth Service]
    B --> D[Feature Service]
    D --> E[Database]
    D --> F[Cache]

Step 4: Design Components and Interfaces

For each major component:

## Components and Interfaces

### [Component Name]
**Purpose:** [What this component does]

**Responsibilities:**
- [Responsibility 1]
- [Responsibility 2]

**Interfaces:**
- Input: [What it receives]
- Output: [What it produces]
- Dependencies: [What it requires]

**API Definition:**
```typescript
interface ComponentName {
  method(input: InputType): Promise<OutputType>;
}

### Step 5: Define Data Models

Document all data structures:

```markdown
## Data Models

### [Entity Name]
**Purpose:** [What this entity represents]

**Properties:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | string | Yes | Unique identifier |
| name | string | Yes | Display name |
| createdAt | Date | Yes | Creation timestamp |

**Validation Rules:**
- [Rule 1]
- [Rule 2]

**Relationships:**
- [Relationship to other entities]

**Example:**
```json
{
  "id": "abc123",
  "name": "Example",
  "createdAt": "2024-01-15T10:30:00Z"
}

### Step 6: Plan Error Handling

Document error scenarios:

```markdown
## Error Handling

### Error Categories
1. **Validation Errors:** Invalid user input
2. **Authentication Errors:** Unauthorized access
3. **External Service Errors:** Third-party failures
4. **System Errors:** Internal failures

### Error Response Strategy

| Error Type | HTTP Code | User Message | System Action |
|------------|-----------|--------------|---------------|
| Validation | 400 | Specific field error | Log, return details |
| Auth | 401 | "Please log in" | Redirect to login |
| Not Found | 404 | "Resource not found" | Log, return error |
| Server | 500 | "Something went wrong" | Log, alert, retry |

### Recovery Mechanisms
- [Retry strategies]
- [Fallback behaviors]
- [Circuit breaker patterns]

Step 7: Define Testing Strategy

## Testing Strategy

### Unit Testing
- **Coverage Target:** 80%+
- **Focus Areas:** [Critical business logic]
- **Mocking Strategy:** [What to mock]

### Integration Testing
- **Scope:** [Component interactions to test]
- **Environment:** [Test environment setup]
- **Data Strategy:** [Test data approach]

### End-to-End Testing
- **Critical Paths:** [User journeys to test]
- **Tools:** [Testing tools]

### Performance Testing
- **Load Targets:** [Expected load]
- **Benchmarks:** [Performance requirements]

Decision Documentation

Document key decisions using this template:

### Decision: [Brief Title]

**Context:** [Situation requiring a decision]

**Options Considered:**

**Option 1: [Name]**
- Pros: [Benefits]
- Cons: [Drawbacks]
- Effort: [Low/Medium/High]

**Option 2: [Name]**
- Pros: [Benefits]
- Cons: [Drawbacks]
- Effort: [Low/Medium/High]

**Decision:** [Chosen option]

**Rationale:** [Why this option was selected]

**Implications:** [What this means for implementation]

Common Design Decisions

API Design

### Decision: API Architecture

**Options:**
1. **REST API** - Standard HTTP methods, well-understood
2. **GraphQL** - Flexible queries, single endpoint