design

Design Mode

Recommended model tier: smart (opus) - this skill requires complex reasoning

Output a technical design specification that downstream SDLC stages can consume.

Purpose

Create a structured design document that defines:

1. What to build (interfaces, types, components)
2. How it fits together (data flow, interactions)
3. Why key decisions were made (rationale)
4. Success criteria (acceptance criteria for TEST stage)

Workflow

Step 1: Understand the Request

Read the request and identify:

• Core functionality required
• Constraints (tech stack, patterns, performance)
• Integration points with existing code

Step 2: Explore the Codebase

Use search tools to understand existing patterns:

• Use Grep for similar patterns, interfaces, types
• Use Glob for relevant files
• Use mcp__plugin_aide_aide__decision_list to review all decisions
• Use mcp__plugin_aide_aide__decision_get with the relevant topic to check specific decisions

Step 3: Define Interfaces

Define the public API/interfaces first:

// Example TypeScript interface
interface UserService {
  createUser(data: CreateUserInput): Promise<User>;
  getUser(id: string): Promise<User | null>;
  updateUser(id: string, data: UpdateUserInput): Promise<User>;
}

interface CreateUserInput {
  email: string;
  name: string;
}

// Example Go interface
type UserService interface {
    CreateUser(ctx context.Context, input CreateUserInput) (*User, error)
    GetUser(ctx context.Context, id string) (*User, error)
    UpdateUser(ctx context.Context, id string, input UpdateUserInput) (*User, error)
}

Step 4: Document Data Flow

Describe how components interact:

Request → Controller → Service → Repository → Database
                ↓
           Validator
                ↓
          Error Handler → Response

Step 5: Record Key Decisions

Store architectural decisions for future reference:

./.aide/bin/aide decision set "<feature>-storage" "PostgreSQL with JSONB for metadata" \
  --rationale="Need flexible schema for user preferences" --by="<git-username>"

./.aide/bin/aide decision set "<feature>-auth" "JWT with refresh tokens" \
  --rationale="Stateless auth, mobile client support" --by="<git-username>"