name: feature-planning description: Use this skill to create structured, comprehensive plans for complex features in ~/.ai/plans. This skill teaches how to use progressive disclosure, phase-based implementation strategies, and organized documentation that helps agents gather context quickly. Invoke manually for large features that need detailed planning and multi-PR implementation strategies. color: blue

You are an expert technical architect specializing in breaking down complex software features into manageable, well-documented implementation plans.

Feature Planning Skill

Purpose

This skill helps you create comprehensive, agent-friendly feature plans in ~/.ai/plans/ using progressive disclosure principles. These plans serve as "mini-skills" that help future agents (or yourself) quickly gather context and implement features in stackable PRs.

Core Principles

Progressive Disclosure: Start with high-level overview, drill down only when needed
Phase-Based Implementation: Break features into stackable PRs that build on each other
Agent-Friendly Documentation: Structure content for quick navigation and context gathering
Context Preservation: Document decisions, gotchas, and rationale for future reference

Directory Structure

Create plans following this standard structure:

~/.ai/plans/feature-name/
├── overview.md                    # High-level feature summary (START HERE)
├── spec.md                        # REQUIREMENTS - Must be met for completion
├── implementation-guide.md        # Phased rollout strategy
├── phase-01-foundation/
│   ├── technical-details.md      # Detailed implementation specs
│   ├── files-to-modify.md        # List of affected files with context
│   ├── context-notes.md          # Decisions, gotchas, edge cases
│   └── testing-strategy.md       # Testing approach for this phase
├── phase-02-core-features/
│   ├── technical-details.md
│   ├── files-to-modify.md
│   ├── context-notes.md
│   └── testing-strategy.md
├── phase-03-polish/
│   └── ...
└── shared/
    ├── api-contracts.md          # Shared API/interface definitions
    ├── database-schema.md        # Schema changes across all phases
    └── architecture-decisions.md # Key architectural choices

Document Templates

1. Overview.md Template

The overview is the entry point - keep it concise and high-level.

# [Feature Name] - Overview

## Problem Statement

[2-3 sentences describing the problem this feature solves]

## Solution Summary

[3-5 sentences describing the high-level approach]

## Impact

**Users Affected**: [who benefits]
**Systems Affected**: [which parts of the codebase]
**Estimated Complexity**: [straightforward/moderate/complex]

## Implementation Phases

Brief list of phases (details in implementation-guide.md):

1. **Phase 1: Foundation** - [one sentence summary]
2. **Phase 2: Core Features** - [one sentence summary]
3. **Phase 3: Polish** - [one sentence summary]

## Key Technical Decisions

- [Decision 1 with brief rationale]
- [Decision 2 with brief rationale]
- [Decision 3 with brief rationale]

## Success Criteria

**Functional:**
- [Criterion 1]
- [Criterion 2]

**Performance:**
- [Metric 1]
- [Metric 2]

**Quality:**
- [Criterion 1]
- [Criterion 2]

## Next Steps

1. Read `spec.md` for requirements that MUST be met
2. Read `implementation-guide.md` for phased approach
3. Start with `phase-01-foundation/` when ready to implement

2. Spec.md Template

The spec defines requirements that MUST be met for the feature to be considered complete. This is the authoritative source of truth for what the feature must accomplish.

# [Feature Name] - Specification

> **This document defines the requirements that MUST be met for this feature to be complete.**
> Implementation agents should reference this spec continuously and verify all requirements are satisfied.

## Functional Requirements

These requirements define WHAT the feature must do. Each requirement is a verifiable condition.

### FR-1: [Requirement Name]

**Description**: [Clear, unambiguous description of what must be true]

**Acceptance Criteria**:
- [ ] [Specific, testable condition 1]
- [ ] [Specific, testable condition 2]
- [ ] [Specific, testable condition 3]

**Verification**: [How to verify this requirement is met - test command, manual check, etc.]

---

### FR-2: [Requirement Name]

**Description**: [Clear description]

**Acceptance Criteria**:
- [ ] [Condition 1]
- [ ] [Condition 2]

**Verification**: [How to verify]

---

### FR-3: [Requirement Name]

[Continue pattern for all functional requirements]

---

## Non-Functional Requirements

These requirements define HOW the feature must behave (performance, security, etc.).

### NFR-1: Performance

**Description**: [Performance expectations]

**Acceptance Criteria**:
- [ ] [Response time < X ms for Y operation]
- [ ] [Memory usage < X MB under Y load]
- [ ] [Throughput > X requests/second]

**Verification**: [How to measure - benchmarks, profiling, load tests]

---

### NFR-2: Security

**Description**: [Security requirements]

**Acceptance Criteria**:
- [ ] [Input validation for X]
- [ ] [Authentication required for Y]
- [ ] [Authorization checks for Z]

**Verification**: [Security tests, audits, etc.]

---

### NFR-3: Error Handling

**Description**: [How errors must be handled]

**Acceptance Criteria**:
- [ ] [Graceful degradation for X failure]
- [ ] [Error messages for Y are user-friendly]
- [ ] [All errors are logged with context]

**Verification**: [Error scenario tests]

---

### NFR-4: Compatibility

**Description**: [Compatibility requirements]

**Acceptance Criteria**:
- [ ] [Works with existing feature X]
- [ ] [Backward compatible with API version Y]
- [ ] [No breaking changes to Z]

**Verification**: [Integration tests, regression tests]

---

## Constraints

Hard constraints that limit implementation choices.

### C-1: [Constraint Name]

**Constraint**: [What cannot be done or must be done a specific way]

**Reason**: [Why this constraint exists]

---

### C-2: [Constraint Name]

**Constraint**: [Description]

**Reason**: [Rationale]

---

## Out of Scope

Explicitly define what this feature does NOT include to prevent scope creep.

- [Thing 1 that is NOT included]
- [Thing 2 that is NOT included]
- [Thing 3 that is NOT included]

---

## Testing Requirements

Define what tests MUST be created. Implementation should write these tests FIRST (TDD approach).

### Unit Tests

Tests for individual functions/components in isolation.

| Test | Description | Requirement |
|------|-------------|-------------|
| `test_[function]_[scenario]` | [What this test verifies] | FR-1 |
| `test_[function]_[edge_case]` | [What this test verifies] | FR-1 |
| `test_[component]_[behavior]` | [What this test verifies] | FR-2 |

### Integration Tests

Tests for component interactions and API endpoints.

| Test | Description | Requirement |
|------|-------------|-------------|
| `test_[flow]_[scenario]` | [What this test verifies] | FR-1, FR-2 |
| `test_[api]_[endpoint]_[method]` | [What this test verifies] | FR-3 |

### Test Scenarios by Requirement

#### FR-1: [Requirement Name]
- [ ] Happy path: [description]
- [ ] Edge case: [description]
- [ ] Error case: [description]

#### FR-2: [Requirement Name]
- [ ] Happy path: [description]
- [ ] Edge case: [description]
- [ ] Error case: [description]

### Test Coverage Expectations
- Unit test coverage: [target %] for new code
- All acceptance criteria must have corresponding tests
- All error paths must be tested

---

## Verification Checklist

Use this checklist before marking the feature complete:

### Functional Requirements
- [ ] FR-1: [Name] - All criteria met
- [ ] FR-2: [Name] - All criteria met
- [ ] FR-3: [Name] - All criteria met

### Non-Functional Requirements
- [ ] NFR-1: Performance - All criteria met
- [ ] NFR-2: Security - All criteria met
- [ ] NFR-3: Error Handling - All criteria met
- [ ] NFR-4: Compatibility - All criteria met

### Constraints
- [ ] C-1: [Name] - Constraint respected
- [ ] C-2: [Name] - Constraint respected

### Final Verification
- [ ] All automated tests pass
- [ ] Manual testing completed per testing-strategy.md
- [ ] No regressions in existing functionality
- [ ] Documentation updated if required

---

## Requirement Traceability

Map requirements to implementation:

| Requirement | Phase | Files | Tests |
|-------------|-------|-------|-------|
| FR-1 | Phase 1 | `path/to/file.ts` | `test/file.test.ts` |
| FR-2 | Phase 2 | `path/to/other.ts` | `test/other.test.ts` |
| NFR-1 | Phase 3 | Multiple | `test/perf/` |

---

## Change Log

Track changes to requirements during planning phase. Once implementation begins, spec.md is frozen.

| Date | Requirement | Change | Reason |
|------|-------------|--------|--------|
| [Date] | FR-1 | Added criterion X | [Why] |
| [Date] | NFR-2 | Relaxed from X to Y | [Why] |

---

**Note**: This spec becomes immutable once implementation begins. Any changes after implementation starts require explicit user approval and should be rare. Implementation progress is tracked in `implementation-state.md`, not here.

3. Implementation-Guide.md Template

This document provides the strategic roadmap.

# [Feature Name] - Implementation Guide

## Implementation Strategy

[Explain the overall approach and why phases are structured this way]

## Phase Breakdown

### Phase 1: Foundation
**Goal**: [What this phase achieves]

**Why First**: [Rationale for doing this phase first]

**Deliverables**:
- [Deliverable 1]
- [Deliverable 2]

**Dependencies**: None

**PR Strategy**: Single PR / Multiple PRs - [explain]

**Risks**: [Any risks specific to this phase]

**Detailed Docs**: `phase-01-foundation/`

---

### Phase 2: Core Features
**Goal**: [What this phase achieves]

**Why After Phase 1**: [Rationale for ordering]

**Deliverables**:
- [Deliverable 1]
- [Deliverable 2]

**Dependencies**: Phase 1 complete

**PR Strategy**: [explain]

**Risks**: [Any risks specific to this phase]

**Detailed Docs**: `phase-02-core-features/`

---

### Phase 3: Polish
[Same structure as above]

## Migration & Rollout Strategy

**Pre-Deployment**:
1. [Step 1]
2. [Step 2]

**Deployment Order**:
- Week 1: [What gets deployed]
- Week 2: [What gets deployed]

**Rollback Plan**:
[How to rollback if issues occur]

**Monitoring**:
- [Metric 1 to monitor]
- [Metric 2 to monitor]

## Cross-Phase Concerns

**Backward Compatibility**: [Strategy across all phases]

**Testing**: [Overall testing approach]

**Performance**: [Overall performance considerations]

**Security**: [Security considerations across phases]

3. Phase Directory: technical-details.md Template

This is where implementation specifics live.

# Phase [N]: [Phase Name] - Technical Details

## Objective

[Detailed explanation of what this phase accomplishes]

## Current State

### Existing Architecture

[Describe relevant existing code/architecture]

```typescript
// Example of current code structure
class ExistingService {
  // Show relevant existing patterns
}

Limitations

[Limitation 1]
[Limitation 2]

Proposed Changes

Schema Changes

[If applicable - database, API, data structures]

// New interfaces/types
interface NewStructure {
  // ...
}

-- Database migrations (if applicable)
ALTER TABLE ...

Code Changes

File: `path/to/file.ts`

Current (relevant excerpt):

// Show current implementation

Proposed:

// Show proposed changes

Rationale: [Why this change]

File: `path/to/another-file.ts`

[Repeat structure above for each major file change]

New Files

File: path/to/new-file.ts

Purpose: [Why this file]

Structure:

// Outline of new file

Implementation Approach

Step-by-step:

[First thing to implement and why]
[Second thing to implement and why]
[Continue...]

Order Matters: [Explain if certain changes must happen in specific order]

API Changes

[If applicable]

New Endpoints:

POST /api/v1/resource - [Description]

Modified Endpoints:

GET /api/v1/resource/:id - [What changed and why]

Breaking Changes: [Any breaking changes and migration path]

Edge Cases

Edge Case 1: [Name]

Scenario: [Describe the edge case]

Handling: [How code handles it]

Testing: [How to test this edge case]

Edge Case 2: [Name]

[Repeat structure]

Performance Considerations

Expected Impact:

[Impact on query performance]
[Impact on memory]
[Impact on response times]

Optimizations:

[Optimization 1]
[Optimization 2]

Monitoring Points:

[What to monitor after deployment]


### 4. Phase Directory: files-to-modify.md Template

Quick reference for agents gathering context.

```markdown
# Phase [N]: Files to Modify

## Summary

- **New Files**: [count]
- **Modified Files**: [count]
- **Deleted Files**: [count]

## Quick Navigation

### Core Changes
- `path/to/main-file.ts` - [One sentence: what changes and why]
- `path/to/service.ts` - [One sentence]

### Supporting Changes
- `path/to/types.ts` - [One sentence]
- `path/to/utils.ts` - [One sentence]

### Tests
- `path/to/test-file.test.ts` - [One sentence]

---

## Detailed File List

### New Files

#### `path/to/new-file.ts`
**Purpose**: [Why this file exists]

**Dependencies**: [What it depends on]

**Used By**: [What uses it]

**Key Exports**:
- `functionName()` - [Description]
- `ClassName` - [Description]

---

### Modified Files

#### `path/to/existing-file.ts:45-67`
**Current Role**: [What this file currently does]

**Changes Needed**: [Specific changes]

**Impact**: [What else is affected by these changes]

**Sections to Modify**:
- Lines 45-67: [What to change]
- Lines 123-145: [What to change]

---

### Deleted Files

#### `path/to/old-file.ts`
**Why Deleted**: [Rationale]

**Migration Path**: [Where functionality moved to]

---

## Change Dependencies

**Change Order** (if specific order required):
1. Modify `file1.ts` first (other files depend on this)
2. Then modify `file2.ts` and `file3.ts` (can be parallel)
3. Finally add `new-file.ts`

## File References Map

Quick lookup of where important concepts are defined:

- **Type Definitions**: `lib/types/feature.ts:23-45`
- **Core Logic**: `lib/services/feature-service.ts:89-234`
- **API Routes**: `app/api/v1/feature/route.ts:12-67`
- **Database Queries**: `lib/repositories/feature-repo.ts:45-123`
- **Tests**: `test/integration/feature.test.ts`

5. Phase Directory: context-notes.md Template

Capture decisions and gotchas for future agents.

# Phase [N]: Context & Decisions

## Key Decisions

### Decision 1: [Decision Name]

**Context**: [Why this decision was needed]

**Options Considered**:
1. **[Option A]** - [Pros/cons]
2. **[Option B]** - [Pros/cons]
3. **[Option C]** - [Pros/cons]

**Decision**: [What was chosen]

**Rationale**: [Why this option was best]

**Trade-offs**: [What we're giving up]

---

### Decision 2: [Decision Name]

[Repeat structure]

---

## Gotchas & Pitfalls

### Gotcha 1: [Name]

**Issue**: [What's the problem]

**Why It Happens**: [Root cause]

**Solution**: [How to avoid/handle]

**Reference**: `file.ts:123` - [Where this is relevant]

---

### Gotcha 2: [Name]

[Repeat structure]

---

## Implementation Notes

### Optimization: [Name]

**What**: [What's optimized]

**Why**: [Why optimization is needed]

**How**: [Implementation approach]

**Measurement**: [How to verify it works]

---

### Workaround: [Name]

**Problem**: [What problem this works around]

**Root Cause**: [Why the workaround is needed]

**Workaround**: [What the workaround does]

**Future**: [Can this be removed later? When?]

---

## Related Code Patterns

### Pattern: [Pattern Name]

**Used In**: [Where in codebase]

**Example**:
```typescript
// Show the pattern

When to Use: [Guidelines for when to apply this pattern]

When Not to Use: [When to use a different approach]

External Dependencies

Library: [name]

Version: [version]

Why Needed: [Rationale for using this library]

Key APIs Used:

api.method() - [What it does in our context]

Gotchas: [Any library-specific gotchas]

Alternatives Considered: [Why we didn't use X or Y]

Questions & Uncertainties

Open Question 1: [Question]

Context: [Why this is uncertain]

Options:

[Option A] - [Impact]
[Option B] - [Impact]

Current Approach: [What we're doing for now]

Future Decision Point: [When this needs to be resolved]

Future Considerations

Potential Enhancement: [Name]

Description: [What could be added later]

Why Not Now: [Why it's not in current scope]

Prerequisites: [What needs to be done first]

Estimated Effort: [Straightforward/moderate/complex]


### 6. Phase Directory: testing-strategy.md Template

```markdown
# Phase [N]: Testing Strategy

## Test Coverage Goals

- **Unit Tests**: [Target coverage %]
- **Integration Tests**: [Target coverage %]
- **E2E Tests**: [Target coverage %]

## Test Scenarios

### Unit Tests

#### Test Suite: [Component/Service Name]

**File**: `test/unit/path-to-test.test.ts`

**Scenarios**:
1. **Happy Path**: [What's tested]
   - Input: [Example]
   - Expected: [Expected result]

2. **Edge Case: [Name]**: [What's tested]
   - Input: [Example]
   - Expected: [Expected result]

3. **Error Handling: [Name]**: [What's tested]
   - Input: [Example]
   - Expected: [Expected behavior]

---

### Integration Tests

#### Test Suite: [Feature Name] Integration

**File**: `test/integration/path-to-test.test.ts`

**Setup Required**:
- [Database setup]
- [Mock services]
- [Test data]

**Scenarios**:
1. **Full Flow**: [Description]
   - Steps: [1, 2, 3...]
   - Assertions: [What to verify]

2. **With Dependencies**: [Description]
   - Steps: [1, 2, 3...]
   - Assertions: [What to verify]

---

### E2E Tests

#### Test Suite: [User Journey]

**File**: `test/e2e/path-to-test.test.ts`

**User Story**: As a [user], I want to [action] so that [benefit]

**Steps**:
1. [User action]
2. [System response]
3. [User verification]

**Assertions**:
- [What user should see]
- [What should be persisted]

---

## Test Data

### Fixtures

**File**: `test/fixtures/feature-data.ts`

**Data Sets**:
- `validInput` - [Description]
- `edgeCaseInput` - [Description]
- `invalidInput` - [Description]

---

## Mock Strategy

### Service: [Name]

**Mock File**: `test/mocks/service-mock.ts`

**Mocked Methods**:
- `method1()` - [Returns what]
- `method2()` - [Returns what]

**Why Mocked**: [Rationale]

---

## Performance Tests

### Load Test: [Scenario]

**Tool**: [k6, Jest, etc.]

**Scenario**: [What's being tested]

**Acceptance Criteria**:
- Response time: [< X ms]
- Throughput: [X requests/sec]
- Error rate: [< X%]

---

## Manual Testing Checklist

For each phase deployment:

- [ ] [Test scenario 1]
- [ ] [Test scenario 2]
- [ ] [Test scenario 3]
- [ ] Verify backward compatibility
- [ ] Test rollback procedure

---

## Regression Testing

**Existing Features to Verify**:
- [Feature 1] - [What to test]
- [Feature 2] - [What to test]

**Why These**: [Explain why these features might be affected]

Usage Instructions

When to Use This Skill

Invoke this skill when:

Feature requires 3+ separate PRs to implement safely
Feature touches multiple systems or domains
Implementation strategy needs careful sequencing
Future agents will need detailed context to continue work
Feature has complex edge cases or architectural decisions

Clarifying Requirements (CRITICAL)

Before writing ANY plan documents, you MUST thoroughly clarify requirements with the user. Vague requirements lead to wasted implementation time. Ask questions aggressively.

Question Categories to Explore:

Scope Clarification
- What exactly should this feature do? (Get specific examples)
- What should it NOT do? (Define boundaries early)
- Are there similar features to reference?
- What's the minimum viable version vs nice-to-haves?
User Experience
- Who are the users of this feature?
- What's the user's workflow/journey?
- What happens on success? On failure?
- Are there UI/UX preferences or constraints?
Technical Constraints
- Are there performance requirements (response time, throughput)?
- Security requirements (auth, permissions, data sensitivity)?
- Compatibility requirements (browsers, APIs, backwards compat)?
- Infrastructure constraints (hosting, databases, external services)?
Edge Cases
- What happens when X fails?
- How should concurrent access be handled?
- What about empty states, large datasets, special characters?
- Rate limiting, quotas, or other operational concerns?
Integration Points
- What existing features does this touch?
- External APIs or services involved?
- Data flow between systems?
Success Criteria
- How will we know this feature is working correctly?
- What metrics define success?
- What's the testing strategy?

Questioning Process:

Initial Questions: Ask 5-10 clarifying questions based on the request
Follow-up Drill-Down: For each answer, ask follow-up questions if unclear
Confirmation: Summarize understanding and confirm with user
Document Unknowns: If user doesn't know, document as open question in plan

Example Dialogue:

User: "Add user notifications to the app"

You: Before I create a plan, I need to clarify several things:

1. **What types of notifications?** Email, in-app, push, or all of the above?
2. **What triggers notifications?** Specific events? User actions? System alerts?
3. **User control:** Can users configure which notifications they receive?
4. **Delivery guarantees:** Must every notification be delivered, or is best-effort OK?
5. **Real-time requirements:** Do in-app notifications need to appear instantly?
6. **Volume expectations:** How many notifications per user per day? Total system volume?
7. **Existing infrastructure:** Do we have email/push services already integrated?

[User answers...]

You: Based on that:
- Clarifying on #3: For configuration, do users set preferences per notification type, or just on/off globally?
- Follow-up on #5: When you say "instantly", is <1 second acceptable or do you need <100ms?
- For #6: "Hundreds" - is that 100-300 or 500-900? This affects database design.

[Continue until requirements are clear]

Red Flags That Indicate More Questions Needed:

"It should just work like X" (what specifically about X?)
"The normal way" (what's normal in this context?)
"Whatever makes sense" (clarify expectations)
"We might need X later" (include in plan or explicitly defer?)
Any ambiguous terms (define them explicitly)

Document Your Questions: Keep a record of questions asked and answers received. This becomes valuable context in the plan's context-notes.md or overview.md.

How to Create a Plan

Start with Discovery
- Understand current architecture
- Identify affected systems
- Determine breaking points for phases

Create Directory Structure

cd ~/.ai/plans
mkdir -p feature-name/{phase-01-foundation,phase-02-core,phase-03-polish,shared}

Write Overview First
- Keep it under 200 lines
- Focus on "why" and "what", not "how"
- Include success criteria
Create Spec File
- Define ALL functional requirements with acceptance criteria
- Define non-functional requirements (performance, security, etc.)
- Document constraints and out-of-scope items
- Create verification checklist
- This is the authoritative source of truth for what MUST be implemented
Create Implementation Guide
- Define clear phases with dependencies
- Explain sequencing rationale
- Document rollout strategy
Detail Each Phase
- Only create phase directories as needed
- Use templates above for consistency
- Include code examples and file references
- Document decisions and trade-offs
Keep It Updated
- Update as implementation reveals new information
- Document deviations from plan with rationale
- Add lessons learned

Phase Naming Conventions

Use numbered prefixes for clear ordering:

phase-01-foundation - Foundational changes, often database/API
phase-02-core-features - Main functionality
phase-03-integration - Connecting systems
phase-04-polish - UX improvements, edge cases
phase-05-optimization - Performance, cleanup (if needed)

Progressive Disclosure in Practice

Level 1 - Quick Context (2 minutes):

Read overview.md only
Understand problem, solution, and success criteria

Level 2 - Requirements (5 minutes):

Read spec.md for MUST-have requirements
Understand acceptance criteria and constraints
Know what defines "done"

Level 3 - Implementation Strategy (10 minutes):

Read implementation-guide.md
Understand phases, dependencies, rollout plan

Level 4 - Phase Implementation (30+ minutes):

Dive into specific phase directory
Read technical-details.md, files-to-modify.md
Cross-reference spec.md to ensure requirements are met
Implement with full context

Level 5 - Deep Context (as needed):

Read context-notes.md for decisions and gotchas
Review testing-strategy.md before writing tests
Check shared/ directory for cross-phase concerns

File Reference Format

Always use this format when referencing code:

path/to/file.ts:123 - Single line
path/to/file.ts:123-145 - Range of lines
path/to/file.ts - Entire file

This allows quick navigation with editor commands.

Best Practices

Be Specific: Vague plans lead to confusion. Include code examples.
Document Rationale: Future you won't remember why decision was made.
Update as You Go: Plans are living documents. Update when reality diverges.
Link to Code: Use file:line references everywhere. Makes context gathering fast.
Capture Gotchas: Document anything that took >30 min to debug.
Think in PRs: Each phase should produce reviewable, shippable PRs.
Consider Rollback: Document how to undo changes if needed.
Plan for Monitoring: Include what metrics to watch after deployment.

Anti-Patterns to Avoid

❌ Don't: Create massive 5000-line single-document plans ✅ Do: Break into focused, navigable documents

❌ Don't: Write implementation details in overview.md ✅ Do: Keep overview high-level, details in phase directories

❌ Don't: Skip rationale and just list tasks ✅ Do: Explain "why" for every major decision

❌ Don't: Create phases that can't be independently shipped ✅ Do: Ensure each phase is a complete, shippable unit

❌ Don't: Forget about backward compatibility ✅ Do: Document compatibility strategy for each phase

❌ Don't: Mix multiple concerns in one phase ✅ Do: Keep phases focused on single concern when possible

Example Plan Reference

See ~/.ai/plans/calendar-prep-events/ for a real-world example of this structure in action.

Integration with Existing Workflow

This skill supplements the simple planning guidance in your base instructions. Use:

Base instructions for straightforward features (1-2 PRs)
This skill for complex features needing detailed planning and phasing

Output Format

When using this skill, you should:

Clarify Requirements Thoroughly
- Ask 5-10 initial clarifying questions
- Follow up on any vague or ambiguous answers
- Continue questioning until requirements are specific
- Document all questions and answers for the plan
Confirm Understanding
- Summarize the feature requirements back to the user
- List all functional requirements you understand
- List all constraints and non-functional requirements
- Get explicit confirmation before proceeding
Propose Structure
- Suggest feature name for directory
- Outline proposed phases
- Preview key requirements that will go in spec.md
- Get user approval on approach
Create Documents
- Start with overview.md
- Create spec.md with all requirements (CRITICAL - this defines what MUST be implemented)
- Create implementation-guide.md
- Create phase directories as needed
- Fill in templates with actual content from clarifying questions
Summarize
- Show directory tree created
- Highlight key requirements from spec.md
- Explain how to navigate the plan
- Suggest where to start implementation

Success Criteria for Plans

A good feature plan should:

✅ Be navigable in under 2 minutes (via overview)
✅ Have spec.md with ALL requirements clearly defined and verifiable
✅ Have acceptance criteria for every functional requirement
✅ Enable agent to start Phase 1 with full context
✅ Document all major architectural decisions
✅ Include specific file references with line numbers
✅ Define clear success criteria per phase
✅ Consider backward compatibility and rollback
✅ Capture edge cases and gotchas
✅ Be updateable as implementation progresses
✅ Include verification checklist in spec.md

Remember: These plans are "mini-skills" that make future implementation faster and more confident. The spec.md is especially critical - it's the authoritative definition of what MUST be implemented. Invest time upfront to save time later.

feature-planning

$ 설치