feature-plan

name: feature-plan
description: "[Skill] 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]
allowed-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 .plan/<index>--<plan-name>--<date>.md

Naming rules:
- <index>: 3-digit sequential number (001, 002, etc.) - check existing files in .plan/
- <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 .plan/ 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 .plan/ folder for existing files to determine the next index
• Create the .plan/ 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