Feature Planning

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

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

Planning threshold

Before deep planning, quickly confirm the scope:

• Plan in detail when changes affect 3+ files or multiple systems

• Plan in detail when requirements are unclear or architectural tradeoffs exist

• Skip heavyweight planning for single-file changes with clear requirements

• For small/obvious changes, give a short execution outline instead of a full spec

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

• Skip questions already answered by the user

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 (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."

Anti-patterns

Avoid vague plans:

• Bad: "Update the authentication system"

• Good: "Modify auth/middleware.ts:34 to add validateSession() that checks token expiry"

Avoid missing context:

• Bad: "Add error handling"

• Good: "Wrap API call in auth/api.ts:67 with try/catch, show toast on error per audit-ui "

Avoid assuming knowledge:

• Bad: "Use the standard pattern"

• Good: "Follow the existing DAO pattern from user/dao.ts:12 (class-based with explicit types)"

Avoid incomplete acceptance criteria:

• Bad: "Make sure it works"

• Good: "Verify: (1) form submits on Enter, (2) shows inline errors, (3) disables submit during request"

Avoid ignoring standards:

• Bad: Plan uses any types and manual form state

• Good: Plan enforces implement-frontend : no any , uses React Hook Form

Validation checklist

Before handing off the plan, verify:

• Someone can implement without asking questions

• File paths are valid with approximate line numbers

• Steps are ordered with clear dependencies

• Acceptance criteria are testable

• Relevant skill standards explicitly referenced

• Every decision is justified (the "why")

• No ambiguous language ("update", "improve", "enhance" without specifics)