feature-design

name	feature-design
description	Create detailed design documents for specific features before implementation. Use when planning a significant feature, migration, or architectural change that needs options analysis and implementation phases. Edit sections in place as design evolves.

Feature Design Skill

Create detailed design documents for features, migrations, or architectural changes that require upfront planning.

When to Use This Skill

• Planning a significant new feature (multi-day implementation)
• Designing a migration strategy
• Evaluating multiple technical approaches
• Integration work between systems
• Changes that affect multiple parts of the codebase

Don't use for:

• Small features or bug fixes
• Strategic project context (use project-overview skill)
• Tracking ongoing work (use development-plan skill)

File Location

Feature designs typically live alongside the development plan:

dev-plans/
└── {project}/
    ├── features/
    │   ├── 2025-12-29-user-auth-redesign.md
    │   └── 2025-12-15-api-migration.md
    └── current-focus.md

Naming: YYYY-MM-DD-feature-name.md

Document Template

Title and Metadata

# Design: [Feature Name]

**Status:** [Draft / In Review / Approved / Superseded]
**Created:** [Date]
**Updated:** [Date if modified]

---

Status notes:

• Use Superseded when the design was replaced by a different approach (link to new doc)
• Update the Updated date when making significant changes

Executive Summary

One paragraph (3-5 sentences) describing:

• What this feature/change is
• Why it's needed
• The recommended approach (if determined)

## Executive Summary

[Concise description of the feature, the problem it solves, and the high-level approach. Reader should understand the "what" and "why" after this paragraph.]

Current State / Problem

Describe what exists today and why it's insufficient.

## Current State

### How It Works Today

[Describe the current implementation, data flow, or architecture]

### Problems

- [Problem 1 - be specific about the pain point]
- [Problem 2]
- [Problem 3]

### Why Change Now?

[What triggered this work? New requirements, tech debt, performance issues?]

Include when helpful:

• Code snippets showing current patterns
• Diagrams of current data flow
• Links to relevant code locations

Options Analysis

Evaluate different approaches. Required when multiple viable options exist.

## Options Analysis

### Option A: [Name]

**Description:** [How this approach works]

**Pros:**
- [Advantage 1]
- [Advantage 2]

**Cons:**
- [Disadvantage 1]
- [Disadvantage 2]

**Effort:** [Rough estimate - hours/days/weeks]

### Option B: [Name]

[Same structure]

### Option C: [Name]

[Same structure]

### Comparison

| Criteria | Option A | Option B | Option C |
|----------|----------|----------|----------|
| Complexity | Low | Medium | High |
| Risk | Medium | Low | Low |
| Future flexibility | Limited | Good | Best |
| Effort | 2 days | 1 week | 2 weeks |

Guidelines:

• Include at least 2 options when there's a real choice
• Be honest about trade-offs - no option is perfect
• The comparison table helps crystallize the decision

Recommended Approach

State your recommendation clearly with rationale.

## Recommended Approach

**Recommendation:** Option B - [Name]

### Rationale

[2-3 paragraphs explaining why this option is best. Reference the comparison criteria. Acknowledge what you're giving up by not choosing alternatives.]

### Key Trade-offs Accepted

- [Trade-off 1 - what you're accepting by choosing this approach]
- [Trade-off 2]

Technical Design

The meat of the document. Structure depends on what you're designing.

## Technical Design

### Architecture Overview

[High-level description of the design. Include a diagram if helpful.]

### Data Flow

[Describe how data moves through the system]

[ASCII diagram or mermaid flowchart]

### Interface Definitions

[Key interfaces, types, or contracts]

```typescript
interface FooService {
  doThing(input: Input): Promise<Output>;
}

Key Components

[Component 1]

Responsibility: [What it does] Location: path/to/file.ts

[Implementation details]

[Component 2]

[Same structure]

Integration Points

[How this connects to existing systems]

• [System A]: [How it integrates]
• [System B]: [How it integrates]

**Include what's relevant:**
- Directory structure for new code
- Database schema changes
- API endpoints
- State management approach
- Error handling strategy

### Implementation Phases

Break down the work into phases with rough estimates.

```markdown
## Implementation Phases

### Phase 1: [Name] ([Estimate])

**Goal:** [What this phase accomplishes]

**Tasks:**
- [ ] [Task 1]
- [ ] [Task 2]
- [ ] [Task 3]

**Deliverable:** [What's working at the end of this phase]

### Phase 2: [Name] ([Estimate])

**Goal:** [Goal]

**Tasks:**
- [ ] [Tasks]

**Deliverable:** [Deliverable]

### Phase 3: [Name] ([Estimate])

[Same structure]

Guidelines:

• Each phase should produce something testable
• Include estimates even if rough (helps calibrate)
• Tasks can be moved to development-plan for detailed tracking

Open Questions

Capture unresolved decisions or unknowns.

## Open Questions

### Technical

- [ ] [Question 1] - [Context or options being considered]
- [ ] [Question 2]

### Product/Requirements

- [ ] [Question about requirements or scope]

### Dependencies

- [ ] [External dependency or blocker]

Update: Check off questions as they're answered. Add the answer inline or in relevant sections.

---

Updating the Document

Edit in place as the design evolves. Don't preserve outdated information in the main sections.

When to add an Addendum:

• Only if explicitly requested
• When you need to preserve a record of a major pivot (e.g., "we tried X and it failed")
• For post-implementation learnings

## Addendum: [Title] ([Date])

[Content explaining the update, what changed, why]

---

Writing Guidelines

1. Audience: Engineers who will implement this or review the approach
2. Tone: Technical, direct, decision-focused
3. Specificity: Include code examples, file paths, concrete details
4. Trade-offs: Be explicit about what you're gaining and giving up
5. Living document: Update as you learn, don't let it get stale

Section Priority

Always include:

• Executive Summary
• Current State / Problem
• Recommended Approach (even if tentative)
• Implementation Phases

Include when relevant:

• Options Analysis (when multiple approaches exist)
• Technical Design (depth depends on complexity)
• Open Questions (if unresolved items exist)

Rarely needed:

• Addendums (only when explicitly requested)

Common Pitfalls

• ❌ Analysis paralysis: Don't wait for perfect information - make a recommendation
• ❌ Missing "why": Always explain rationale, not just "what"
• ❌ Stale content: Update or mark as superseded when design changes
• ❌ Too abstract: Include concrete code examples and file paths
• ❌ Ignoring trade-offs: Every choice has downsides - acknowledge them
• ❌ Overly detailed phases: Keep implementation phases high-level; detailed tasks go in development-plan