feature-planning

name	feature-planning
description	Plan before implementing - understand scope and approach with detailed guidance
languages	["all"]
subagents	["all"]
tools_needed	["read","glob"]

Instructions

Step 1: Restate the Goal

Purpose: Ensure alignment before writing code.

How:

• Summarize the feature in 1-2 sentences
• State the problem it solves
• Clarify expected behavior

Example:

"We're adding a password reset feature because users can't recover locked accounts. When a user clicks 'Forgot Password', they should receive an email with a time-limited reset link."

---

Step 2: Read Relevant Source Files

Purpose: Understand existing patterns before proposing changes.

How:

• Use read tool to examine related files
• Identify patterns (naming, error handling, tests)
• Note dependencies and integrations

Common Mistake: ❌ Assuming file structure without reading Correct Approach: ✅ Read first, then propose

---

Step 3: Identify All Files to Change

Purpose: Scope the work and catch integration points.

How:

• List all files that need modification
• Include tests, docs, config
• Note new files to create

Example:

Files to modify:
- src/auth/password_service.py (add reset logic)
- src/api/auth_routes.py (add /reset endpoint)
- tests/test_password_reset.py (new file)
- docs/API.md (document endpoint)

---

Step 4: Propose Implementation Approach

Purpose: Get feedback on design before coding.

Include:

• High-level approach
• Alternative options considered
• Tradeoffs and risks
• Why you chose this approach

Template:

Approach: [Your chosen approach]

Alternatives considered:
1. [Alternative 1] - Pros: X, Cons: Y
2. [Alternative 2] - Pros: X, Cons: Y

Chosen because: [Reasoning]

Risks: [What could go wrong]

---

Step 5: Flag Assumptions

Purpose: Surface uncertainties early.

Examples of assumptions to flag:

• "Assuming we use JWT tokens (not sessions)"
• "Assuming email service is already configured"
• "Assuming password reset links expire after 1 hour"

---

Step 6: Wait for Confirmation

Purpose: Don't waste effort on wrong approach.

What to do:

• Present your plan
• Ask: "Does this approach sound right?"
• Wait for explicit approval
• Don't start coding until confirmed

Why this matters: Prevents rework when assumptions are wrong.

---

Common Mistakes

❌ Starting to code immediately

• Leads to rework when approach is wrong
• Misses integration points
• Creates tech debt

✅ Plan first, then implement

• Catches issues early
• Gets alignment on approach
• Results in cleaner code

❌ Proposing solution without reading code

• Misses existing patterns
• Violates conventions
• Creates inconsistent codebase

✅ Read similar code first

• Matches existing patterns
• Maintains consistency
• Learns from established approaches