SDD Technical Design Generation

Generate comprehensive technical design documents that translate approved requirements into actionable architecture specifications.

Prerequisites

Before generating design:

1. Requirements must be generated using /sdd-requirements
2. Requirements phase should be approved (use sdd-approve requirements MCP tool)
3. Review existing architecture in .spec/steering/tech.md and .spec/steering/structure.md

Workflow

Step 1: Verify Prerequisites

Use sdd-status MCP tool to verify:

• requirements.generated: true
• requirements.approved: true (recommended before design)

Step 2: Review Requirements

1. Read .spec/specs/{feature}/requirements.md
2. Identify all functional requirements (FR-*)
3. Identify all non-functional requirements (NFR-*)
4. Note constraints and assumptions

Step 3: Choose Architecture Pattern

Select appropriate patterns based on requirements:

Step 4: Design Components

For each component, specify:

## Component: {ComponentName}

**Type:** Service | Controller | Repository | Adapter | Provider

**Purpose:** {Single responsibility description}

**Responsibilities:**
- {Responsibility 1}
- {Responsibility 2}

**Interface:**

interface I{ComponentName} { methodName(input: InputType): Promise<OutputType>; }

**Dependencies:**
- {Dependency 1 via interface}
- {Dependency 2 via interface}

**Error Handling:**
- {Error scenario 1}: {How to handle}

Step 5: Define Data Models

## Data Models

### Model: {EntityName}

**Purpose:** {What this entity represents}

| Property | Type | Required | Description | Validation |
|----------|------|----------|-------------|------------|
| id | string | Yes | Unique identifier | UUID format |
| name | string | Yes | Display name | 1-100 chars |
| createdAt | Date | Yes | Creation timestamp | ISO 8601 |

**Relationships:**
- Has many: {RelatedEntity} (one-to-many)
- Belongs to: {ParentEntity} (many-to-one)

**Invariants:**
- {Business rule 1}
- {Business rule 2}

Step 6: Specify Interfaces

## API Interfaces

### REST Endpoints

| Method | Path | Description | Request | Response | Auth |
|--------|------|-------------|---------|----------|------|
| POST | /api/v1/resource | Create resource | CreateDTO | Resource | Bearer |
| GET | /api/v1/resource/:id | Get by ID | - | Resource | Bearer |

### Internal Service Interfaces

Following Interface Segregation Principle:

// Read operations interface IResourceReader { getById(id: string): Promise<Resource>; list(filter: Filter): Promise<Resource[]>; }

// Write operations interface IResourceWriter { create(data: CreateDTO): Promise<Resource>; update(id: string, data: UpdateDTO): Promise<Resource>; delete(id: string): Promise<void>; }

Step 7: Document Error Handling

## Error Handling Strategy

### Error Categories

| Category | HTTP Status | Retry | Log Level |
|----------|-------------|-------|-----------|
| Validation | 400 | No | WARN |
| Not Found | 404 | No | INFO |
| Conflict | 409 | No | WARN |
| Rate Limit | 429 | Yes (backoff) | WARN |
| Internal | 500 | Yes (limited) | ERROR |

### Error Response Format

{ "error": { "code": "VALIDATION_ERROR", "message": "Human-readable message", "details": [{ "field": "email", "issue": "Invalid format" }], "requestId": "uuid-for-tracing" } }

Step 8: Apply Linus-Style Quality Review

Before finalizing, validate against these principles:

1. Taste - Is it elegant?

• Does the design feel natural and intuitive?
• Are there unnecessary complications?

2. Complexity - Is it simple?

• Can any component be simplified?
• Are there too many abstractions?

3. Special Cases - Are edge cases handled?

• What happens at boundaries?
• How does it fail gracefully?

4. Data Structures - Are they optimal?

• Is the right data structure chosen?
• Does data flow make sense?

5. Code Organization - Is it maintainable?

• Can new developers understand it?
• Is it easy to modify?

Step 9: Save and Validate

1. Save design to .spec/specs/{feature}/design.md
2. Use sdd-validate-design MCP tool for GO/NO-GO review
3. If GO, use sdd-approve design MCP tool

Design Document Template

# Design: {Feature Name}

## Overview
{Brief summary of the design approach}

## Architecture Pattern
{Selected pattern and rationale}

## Component Diagram

[Component A] ──> [Component B] │ └──> [Component C]

## Components

### {Component 1}
{Component details as described above}

## Data Models

### {Entity 1}
{Model details as described above}

## Interfaces

### External APIs
{API specifications}

### Internal Interfaces
{Service interfaces}

## Error Handling
{Error strategy}

## Security Considerations
- Authentication: {approach}
- Authorization: {approach}
- Data protection: {approach}

## Testing Strategy
- Unit tests: {coverage target}
- Integration tests: {scope}
- E2E tests: {critical paths}

## Dependencies
- External: {list}
- Internal: {list}

MCP Tool Integration

Steering Document References

Apply these steering documents during design:

Key Linus Principles for Design:

1. Data Structures First: "Bad programmers worry about the code. Good programmers worry about data structures."
2. Eliminate Special Cases: "Good code has no special cases"
3. Simplicity: "If implementation needs more than 3 levels of indentation, redesign it"
4. Never Break Userspace: Ensure backward compatibility

Quality Checklist

• All FR-* requirements have corresponding components
• All NFR-* requirements have technical solutions
• SOLID principles are followed
• Interfaces are well-defined (ISP)
• Dependencies flow inward (DIP)
• Data models are complete with invariants
• Error handling strategy is comprehensive
• Security considerations are addressed
• Testing approach is specified
• Linus-style review passed