name: plan-feature
description: Plan features and complex changes. Use when the user requests a plan/spec, says "detailed plan please", or when changes span multiple files/systems.

Feature Planning

Create concrete, implementation-ready plans for features and complex changes.

DO NOT WRITE CODE during planning. Only explore, analyse, and document.

Scope

Use this skill when:
- User explicitly requests a plan or says "detailed plan please"
- Changes affect 3+ files or multiple systems
- Multiple valid approaches exist and user input is needed
- Requirements are unclear and discovery is needed
- Architectural decisions are required

Skip planning for:
- Single-file changes with clear requirements
- Obvious bug fixes
- Simple additions with no architectural impact

Planning workflow

1. Discovery

Ask targeted questions to uncover intent. For each question:
- Present 2-3 concrete options with tradeoffs
- Give your recommended option with clear reasoning
- One question at a time; wait for user response

Critical questions:
- What problem are you solving? (user pain point, business goal)
- What should happen? (expected behaviour, success criteria)
- What should NOT happen? (constraints, edge cases to avoid)
- Who is this for? (user type, environment, scale)
- How will you verify it works? (testing approach, validation)

Speed-to-learning reference

• Use ship-fast-loop.md for a lightweight shipping loop and feedback cadence.

2. Analysis

Explore the codebase systematically:
- Locate relevant files (use Glob/Grep, document paths with line numbers)
- Map existing patterns (architecture, naming, data flow)
- Identify dependencies (what will be affected by changes)
- Find similar implementations (to maintain consistency)
- Note relevant standards (from implement-frontend, define-architecture, etc)

Document findings:
- File: path/to/file.ts:123 - what it does, how it's relevant
- Pattern: existing approach for similar features
- Constraint: technical limitation or requirement

3. Planning

Create a concrete, ordered plan with:

For each change, specify:
- File path and approximate line number
- Exact function/component/class to modify
- What to add/remove/change (be specific)
- Why this change (how it fits the goal)
- Dependencies (what must happen first)

Plan structure:

## Goal
[One sentence: what we're building and why]

## Changes

### 1. [Description]
- File: `path/to/file.ts:45`
- Action: Add `functionName()` that does X
- Reasoning: Needed because Y
- Dependencies: None

### 2. [Description]
- File: `path/to/other.ts:89`
- Action: Modify `existingFunction()` to handle Z
- Reasoning: Integrates with change #1
- Dependencies: #1 must complete first

## Validation
- [ ] Tests pass
- [ ] Feature works for case A
- [ ] Edge case B is handled
- [ ] Follows `implement-frontend` (if frontend)
- [ ] No console logs or debug code

4. Standards reference

Explicitly note which standards apply:
- Frontend changes: reference implement-frontend, audit-ui
- UI changes: reference design-ui
- Motion: reference ui-animation
- Backend: reference define-architecture
- Typography: reference audit-ui

Format: "This plan must follow implement-frontend for forms and type safety."

5. Validation checklist

Before finalizing, verify the plan includes:
- [ ] Clear goal statement
- [ ] Specific file paths with line numbers
- [ ] Ordered steps (dependencies clear)
- [ ] Acceptance criteria
- [ ] Edge cases considered
- [ ] Relevant skill standards referenced
- [ ] No ambiguous language ("update", "improve", "enhance" without specifics)

Anti-patterns

Avoid vague plans:
- ❌ "Update the authentication system"
- ✅ "Modify auth/middleware.ts:34 to add validateSession() that checks token expiry"

Avoid missing context:
- ❌ "Add error handling"
- ✅ "Wrap API call in auth/api.ts:67 with try/catch, show toast on error per audit-ui"

Avoid assuming knowledge:
- ❌ "Use the standard pattern"
- ✅ "Follow the existing DAO pattern from user/dao.ts:12-45 (class-based with explicit types)"

Avoid incomplete acceptance criteria:
- ❌ "Make sure it works"
- ✅ "Verify: (1) form submits on Enter, (2) shows inline errors, (3) disables submit during request"

Avoid ignoring standards:
- ❌ Plan uses any types and manual form state
- ✅ Plan enforces implement-frontend: no any, uses React Hook Form

Quick checks

Before handing off the plan:
- Can someone implement this without asking questions?
- Are all file paths valid and line numbers approximate?
- Are dependencies between steps clear?
- Are acceptance criteria testable?
- Are relevant skill standards explicitly referenced?
- Is every decision justified (the "why")?

Output format

Deliver the plan as a formatted markdown document that serves as a complete implementation specification. The implementer should not need to make architectural decisions.