feature-planning

Plan before implementing - understand scope and approach with detailed guidance

SKILL.md

GitHub

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