feature-plan

name	feature-plan
description	Create detailed implementation plans for features. Asks clarifying questions, suggests solutions, proposes architecture, and outputs a structured plan document. Use when user wants to plan a feature before coding.
argument-hint	feature description or requirements
metadata	{"tools":["Read","Grep","Glob","Write","AskUserQuestion"]}

Create a comprehensive implementation plan for $ARGUMENTS. This skill helps transform vague requirements into actionable, detailed plans before any code is written.

Planning Process

Phase 1: Understand & Clarify

First, analyze the provided requirements and identify:

• Missing information: What critical details are not specified?
• Ambiguous points: What could be interpreted multiple ways?
• Assumptions: What are you assuming that should be confirmed?
• Dependencies: What existing systems/code does this interact with?

Use AskUserQuestion to clarify ALL unclear points before proceeding. Group related questions together. Examples:

• "Should this feature be accessible to all users or specific roles?"
• "What's the expected data volume/scale?"
• "Are there existing patterns in the codebase to follow?"
• "What's the error handling strategy?"

Do NOT proceed until you have enough clarity to propose solutions.

Phase 2: Explore Codebase

Before suggesting solutions, explore the existing codebase to understand:

• Current architecture and patterns
• Related existing implementations
• Available utilities, hooks, and shared components
• Database schema / API structure (if relevant)
• Testing patterns in use

Phase 3: Suggest Solutions

Present 2-3 distinct approaches with trade-offs:

## Proposed Solutions

### Option A: [Name]
**Approach**: Brief description
**Pros**: List benefits
**Cons**: List drawbacks
**Best for**: When this option is ideal

### Option B: [Name]
**Approach**: Brief description
**Pros**: List benefits
**Cons**: List drawbacks
**Best for**: When this option is ideal

Use AskUserQuestion to let the user pick their preferred approach. Include a recommendation if one option is clearly better for their context.

Phase 4: Gather Resources

Ask the user for any helpful resources:

• Documentation links
• Design files / mockups
• Example implementations to reference
• API specifications
• Related PRs or issues

Phase 5: Create Detailed Plan

After user confirms the approach, create the full plan document.

Output Format

Save the plan to .plans/<index>--<plan-name>--<date>.md

Naming rules:

• <index>: 3-digit sequential number (001, 002, etc.) - check existing files in .plans/
• <plan-name>: kebab-case summary (e.g., user-authentication-flow, product-gallery-redesign)
• <date>: Format MM-DD-YYYY

Document structure:

# [Plan Title]

> **Created**: [Date]
> **Status**: Draft | Ready | In Progress | Completed

---

## Original Prompt

[Paste the exact user input/requirements here]

---

## Summary

[2-3 sentence overview of what this plan covers]

---

## Requirements

### Functional Requirements
- [ ] FR1: Description
- [ ] FR2: Description

### Non-Functional Requirements
- [ ] NFR1: Performance, security, accessibility, etc.

### Out of Scope
- Item 1 (explicitly excluded)

---

## Technical Approach

### Solution Overview
[Describe the chosen approach in 1-2 paragraphs]

### Architecture Diagram (if applicable)
[ASCII diagram or description of component relationships]

---

## Implementation Structure

### Files to Create
| File | Purpose |
|------|---------|
| `path/to/file.ts` | Description |

### Files to Modify
| File | Changes |
|------|---------|
| `path/to/existing.ts` | What changes |

### Folder Structure
```plaintext
src/
├── features/
│   └── [feature-name]/
│       ├── components/
│       ├── hooks/
│       ├── utils/
│       ├── types.ts
│       └── index.ts

---

Instructions

1. Read the requirements carefully from $ARGUMENTS
2. Ask clarifying questions - do not skip this step
3. Explore the codebase to understand existing patterns
4. Present solution options with clear trade-offs
5. Let user choose their preferred approach
6. Ask for resources they want to reference
7. Generate the plan with all sections
8. Save to .plans/ folder with proper naming
9. Keep it under 500 lines - be concise, use tables, avoid verbose explanations

Important Notes

• Always save the original prompt at the top of the document
• Check .plans/ folder for existing files to determine the next index
• Create the .plans/ folder if it doesn't exist
• Focus on actionable items, not theoretical discussions
• Include code structure and type definitions
• Be specific about file paths relative to project root
• The plan should be self-contained - anyone should understand it without extra context