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>"

Attribution (--by): use the git username — the GitHub handle, as in the remote URL — not a display name. Never guess a person's identifier: if you do not know it, omit --by rather than inventing one. The store is append-only, so a wrong byline cannot be edited, only superseded by a new version whose sole change is the name.

Binary location: The aide binary is at .aide/bin/aide. If it's on your $PATH, you can use aide directly.

Step 6: Define Acceptance Criteria

List specific, testable criteria for the TEST stage:

## Acceptance Criteria

- [ ] User can be created with email and name
- [ ] Duplicate emails are rejected with 409 status
- [ ] Created user has UUID identifier
- [ ] User can be retrieved by ID
- [ ] Non-existent user returns null (not error)
- [ ] User email can be updated
- [ ] User name can be updated

Required Output Format

# Design: [Feature Name]

## Overview

[1-2 sentence summary of what this feature does]

## Interfaces

### [Interface/Type Name]

\`\`\`typescript
// Interface definition with comments
\`\`\`

## Data Flow

[Diagram or description of component interactions]

## Key Decisions

| Decision | Choice     | Rationale |
| -------- | ---------- | --------- |
| Storage  | PostgreSQL | [why]     |
| Auth     | JWT        | [why]     |

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Files to Create/Modify

- `path/to/file.ts` - [purpose]
- `path/to/test.ts` - [test scope]

## Dependencies

- [External packages needed]
- [Internal modules to import]

## Out of Scope

- [Explicitly excluded items]

Failure Handling

Unclear Requirements

1. List specific ambiguities
2. State assumptions you're making
3. Record assumptions: ./.aide/bin/aide memory add --category=decision --tags=project:<name>,session:${AIDE_SESSION_ID},source:inferred "Assumed X because Y"
4. Proceed with reasonable defaults

Conflicting Patterns Found

1. Document the conflicting patterns
2. Choose one and record the decision:

   ./.aide/bin/aide decision set "<topic>" "<choice>" --rationale="<why this over alternatives>"
   

Too Large / Too Vague

1. Break into smaller, focused designs
2. Design the core/MVP first
3. Note future phases in "Out of Scope"

Verification Checklist

Before completing design:

• Interfaces are defined with types
• Data flow is documented
• Key decisions are recorded in aide
• Acceptance criteria are testable
• Files to modify are listed
• Dependencies are identified

Memory Hygiene

When storing memories from this skill (assumptions, decisions, discoveries), always:

1. Include source: tag — Use source:inferred for assumptions, source:discovered for findings during exploration
2. Include scope tags — Add project:<name>,session:<id> (get project name from git remote or directory; session ID from $AIDE_SESSION_ID or $CLAUDE_SESSION_ID)
3. Verify codebase claims before storing — If a memory references a file, function, or path, confirm it exists first. See the memorise skill for the full verification workflow.
4. Never use scope:global unless storing a user preference

Completion

When design is complete:

1. Output the full design document
2. Confirm: "Design complete. Ready for TEST stage."

The design document feeds directly into the TEST stage, where acceptance criteria become test cases.