design

name	design
description	Design system architecture, API contracts, and data flows. Use when translating analyzed requirements into technical design for feature implementation.
allowed-tools	Read, Write, Edit, Grep, Glob

Feature Design Skill

Purpose

This skill provides systematic guidance for designing software architecture, API contracts, data models, and workflows based on analyzed requirements.

When to Use

• After requirements analysis is complete
• Need to design technical architecture for a feature
• Defining API contracts and data structures
• Planning module interactions and data flows
• Before starting implementation

Design Workflow

1. Architecture Design

Choose Architectural Pattern: Review architecture-patterns.md for appropriate patterns:

• Layered Architecture: UI → Business Logic → Data Access
• Modular Architecture: Cohesive modules with clear interfaces
• Event-Driven: Message-based communication
• Microservices: Independent, deployable services (if applicable)

For This Project (Python):

• Follow existing structure: src/tools/, src/core/, src/utils/
• Use dependency injection for testability
• Keep files under 500 lines (split if needed)
• Maintain single responsibility principle

Define Components:

Component Name: <name>
Responsibility: <what it does>
Dependencies: <what it needs>
Interfaces: <public API>

Deliverable: Component diagram with responsibilities

2. Data Model Design

Define Entities:

• Identify domain entities from requirements
• Define attributes and types
• Specify relationships (one-to-one, one-to-many, many-to-many)
• Define validation rules
• Consider data lifecycle (CRUD operations)

For Python Projects:

from pydantic import BaseModel, Field
from typing import Optional, List
from datetime import datetime

class EntityModel(BaseModel):
    """Entity description."""
    id: Optional[int] = None
    name: str = Field(..., min_length=1, max_length=255)
    created_at: datetime = Field(default_factory=datetime.utcnow)

    class Config:
        """Pydantic configuration."""
        validate_assignment = True

Deliverable: Data models with Pydantic schemas

3. API Design

Design API Contracts: Refer to api-design-guide.md for best practices

REST API Pattern:

Resource: /api/v1/resources
Methods:
  GET    /resources        - List resources
  GET    /resources/{id}   - Get single resource
  POST   /resources        - Create resource
  PUT    /resources/{id}   - Update resource (full)
  PATCH  /resources/{id}   - Update resource (partial)
  DELETE /resources/{id}   - Delete resource

Request Body:
  {
    "field1": "value",
    "field2": 123
  }

Response Body:
  {
    "data": {...},
    "meta": {
      "timestamp": "2025-01-15T10:30:00Z",
      "version": "1.0"
    }
  }

Error Response:
  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Field validation failed",
      "details": [...]
    }
  }

For Internal APIs (Python Functions/Methods):

def process_feature(
    input_data: InputModel,
    options: Optional[ProcessOptions] = None
) -> ProcessResult:
    """
    Process feature with given input.

    Args:
        input_data: Input data model
        options: Optional processing options

    Returns:
        ProcessResult with outcome

    Raises:
        ValidationError: If input is invalid
        ProcessError: If processing fails
    """
    pass

Deliverable: API specification with request/response formats

4. Data Flow Design

Map Data Flows:

• Input sources (user input, API, database, file)
• Processing steps (validation, transformation, business logic)
• Output destinations (response, database, file, external service)
• Error paths and handling

Sequence Diagram Format:

User → API Endpoint → Validator → Business Logic → Repository → Database
                          ↓             ↓              ↓
                      ValidationError  BusinessError  DatabaseError
                          ↓             ↓              ↓
                      Error Handler → Error Response → User

Deliverable: Sequence diagrams for key workflows

5. Module Interaction Design

Define Module Boundaries:

• Interfaces: Public API contracts (abstract classes, protocols)
• Core Logic: Business logic implementation
• Utilities: Helper functions (pure, stateless)
• Data Access: Repository pattern for persistence

Python Module Structure:

src/tools/feature_name/
├── __init__.py           # Public exports
├── models.py             # Pydantic models
├── interfaces.py         # Abstract interfaces
├── core.py               # Core business logic
├── repository.py         # Data access layer
├── validators.py         # Input validation
├── utils.py              # Helper functions
└── tests/
    ├── test_core.py
    ├── test_validators.py
    └── fixtures.py

Dependency Injection Pattern:

class FeatureService:
    """Service with injected dependencies."""

    def __init__(
        self,
        repository: FeatureRepository,
        validator: FeatureValidator
    ):
        self.repository = repository
        self.validator = validator

Deliverable: Module dependency graph

6. Error Handling Design

Define Error Hierarchy:

class FeatureError(Exception):
    """Base exception for feature."""
    pass

class ValidationError(FeatureError):
    """Input validation failed."""
    pass

class ProcessingError(FeatureError):
    """Processing failed."""
    pass

class NotFoundError(FeatureError):
    """Resource not found."""
    pass

Error Handling Strategy:

• Validate early (fail fast)
• Catch specific exceptions
• Log errors with context
• Return meaningful error messages
• Don't expose internal details

Deliverable: Error handling specification

7. Configuration Design

Externalize Configuration:

from pydantic_settings import BaseSettings

class FeatureConfig(BaseSettings):
    """Feature configuration from environment."""

    api_key: str
    timeout: int = 30
    max_retries: int = 3
    debug: bool = False

    class Config:
        env_prefix = "FEATURE_"
        case_sensitive = False

Configuration Sources:

1. Environment variables (highest priority)
2. .env files
3. Configuration files (JSON/YAML)
4. Default values (lowest priority)

Deliverable: Configuration specification

Output Format

Use the templates/architecture-doc.md template to generate:

# Architecture Design: [Feature Name]

## Overview
Brief description of the feature and design approach.

## Architecture Pattern
[Chosen pattern] with rationale.

## Component Design
### Component 1: [Name]
- **Responsibility**: [What it does]
- **Dependencies**: [What it needs]
- **Interface**: [Public API]

## Data Model
### Entity: [Name]
```python
class EntityModel(BaseModel):
    field: str

API Specification

Endpoint: [Method] [Path]

• Request: [Schema]
• Response: [Schema]
• Errors: [Error codes]

Data Flows

[Sequence diagrams or descriptions]

Module Structure

src/tools/feature/
├── ...

Error Handling

[Exception hierarchy and strategy]

Configuration

[Required configuration with defaults]

Testing Strategy

• Unit tests: [What to test]
• Integration tests: [What to test]
• Mocking strategy: [What to mock]

Security Considerations

[From security-checklist.md in analysis phase]

Performance Considerations

• Expected throughput: [N req/s]
• Response time: [< N ms]
• Resource usage: [Memory, CPU]

Implementation Notes

[Any specific guidance for implementation]

Open Questions

• Question 1
• Question 2

## Best Practices

**Architecture:**
- Prefer composition over inheritance
- Design for testability (dependency injection)
- Keep modules loosely coupled
- Follow SOLID principles
- Keep files under 500 lines

**Data Models:**
- Use Pydantic for validation
- Type hint everything
- Provide sensible defaults
- Document field constraints
- Consider backward compatibility

**APIs:**
- RESTful for external APIs
- Clear function signatures for internal APIs
- Consistent naming conventions
- Version APIs from the start
- Document all parameters and return values

**Error Handling:**
- Create specific exception types
- Log errors with sufficient context
- Don't catch exceptions you can't handle
- Provide actionable error messages
- Consider retry strategies

## Supporting Resources

- **architecture-patterns.md**: Common architectural patterns
- **api-design-guide.md**: API design best practices
- **templates/architecture-doc.md**: Output template

## Example Usage

```bash
# 1. Review analysis report from previous phase
Read docs/implementation/feature-name-analysis.md

# 2. Choose architecture pattern
Review architecture-patterns.md

# 3. Design data models
Create models.py with Pydantic schemas

# 4. Design API contracts
Use api-design-guide.md for REST/function APIs

# 5. Design module structure
Follow project conventions (src/tools/...)

# 6. Generate architecture document
Use templates/architecture-doc.md template

# 7. Review and validate
Check design meets requirements from analysis phase

Integration with Feature Implementation Flow

Input: Requirements analysis report Process: Systematic design using patterns and guidelines Output: Architecture document with specs Next Step: Implementation skill for coding

Design Review Checklist

Before proceeding to implementation:

• Architecture pattern chosen and justified
• All components identified with clear responsibilities
• Data models defined with Pydantic schemas
• API contracts specified (endpoints or function signatures)
• Data flows documented (sequence diagrams)
• Module structure follows project conventions
• Error handling strategy defined
• Configuration externalized
• Testing strategy outlined
• Security considerations addressed
• Performance requirements documented
• Design reviewed by peer (if applicable)
• Stakeholder sign-off (if required)