implementation-planner

name	implementation-planner
description	Create structured implementation plans from validated requirements. Use when requirements are clear and you need to break down implementation into actionable steps with testing approach.

Implementation Planner

Instructions

When to Invoke This Skill

• After requirements are validated and clear
• Before starting implementation work
• User asks for implementation plan
• Complex feature requiring structured approach
• Need to communicate approach to stakeholders

Planning Principles

1. Top-Down Decomposition - Break complex tasks into smaller steps
2. Dependency Ordering - Plan steps in logical sequence
3. Risk Identification - Flag potential issues early
4. Testing Strategy - Define how to verify each step
5. Rollback Plan - Consider how to undo if needed

Standard Workflow

1. Understand the Goal

From validated requirements, extract:

• Primary objective: The main thing being accomplished
• Success criteria: How to know it's done
• Constraints: Technical or business limitations
• Scope boundaries: What's included/excluded

2. Analyze Current State

Investigate existing codebase:

• Related files: What code exists in this area?
• Architecture patterns: How is similar functionality implemented?
• Dependencies: What does this interact with?
• Tests: What test coverage exists?

Use these tools:

• Grep - Search for related code
• Glob - Find relevant files
• Read - Understand existing implementation

3. Identify Components to Modify

List specific files and components:

• Backend changes: API endpoints, business logic, data models
• Frontend changes: UI components, state management
• Database changes: Schema, migrations
• Configuration changes: Settings, environment variables
• Documentation changes: README, API docs

4. Create Step-by-Step Plan

Break down into discrete steps:

Format:

## Implementation Plan

### Step 1: <Component/Area>
**Files to modify:**
- `path/to/file.py` - <what changes>
- `path/to/other.js` - <what changes>

**Changes:**
- <Specific change 1>
- <Specific change 2>

**Testing:**
- <How to test this step>

### Step 2: <Next Component/Area>
...

Guidelines:

• Each step should be independently testable
• Order steps by dependency (do foundation first)
• Estimate complexity: Simple/Moderate/Complex
• Flag risks or unknowns

5. Define Testing Approach

For each type of change:

Backend Changes:

• Unit tests for business logic
• Integration tests for API endpoints
• Manual testing with test server (--port 8001)

Frontend Changes:

• Visual verification in browser
• User interaction testing
• Cross-browser if significant UI change

Data Changes:

• Test migration up and down
• Verify data integrity
• Test with production-like data

6. Identify Risks and Considerations

Common Risks:

• Breaking changes to existing functionality
• Performance impact
• Security implications
• Backward compatibility
• Data migration issues

Document:

• What could go wrong?
• How to mitigate?
• Rollback strategy if needed?

Plan Templates

Feature Addition Template

## Implementation Plan: <Feature Name>

### Overview
<1-2 sentence summary of what's being added>

### Architecture Decision
<Key design choice and rationale>

### Step 1: Data Layer
**Files:**
- `src/models.py` - Add new model
- `src/storage.py` - Add persistence methods

**Changes:**
- Define data structure
- Add CRUD operations
- Add validation

**Testing:**
- Unit tests for model
- Test storage operations

### Step 2: Business Logic
**Files:**
- `src/manager.py` - Add business logic

**Changes:**
- Implement core functionality
- Handle edge cases
- Add error handling

**Testing:**
- Unit tests for logic
- Integration tests

### Step 3: API Layer
**Files:**
- `src/web_server.py` - Add endpoints

**Changes:**
- Add REST endpoints
- Add input validation
- Add error responses

**Testing:**
- Test with curl/Postman
- Verify error cases

### Step 4: Frontend
**Files:**
- `frontend/src/components/...` - Add UI

**Changes:**
- Create component
- Wire up API calls
- Add user feedback

**Testing:**
- Manual browser testing
- Test all user flows

### Risks
- <Potential issue 1>
- <Potential issue 2>

### Rollback Plan
<How to undo if needed>

Bug Fix Template

## Implementation Plan: Fix <Bug Description>

### Root Cause
<What's causing the bug>

### Impact Analysis
<What's affected by this bug>

### Fix Approach
<How to fix it>

### Step 1: Add Test to Reproduce
**Files:**
- `src/tests/test_<area>.py` - Add failing test

**Changes:**
- Create test case that reproduces bug
- Verify test fails with current code

### Step 2: Implement Fix
**Files:**
- `src/<area>.py` - Apply fix

**Changes:**
- <Specific code change>

**Testing:**
- Run test - should now pass
- Manual verification

### Step 3: Add Regression Tests
**Files:**
- Add edge case tests

**Changes:**
- Test boundary conditions
- Test related scenarios

### Verification
- All existing tests still pass
- New tests pass
- Manual testing confirms fix

Refactor Template

## Implementation Plan: Refactor <Component>

### Goal
<Why refactoring - what improves>

### Current Structure
<How it works now>

### Proposed Structure
<How it will work>

### Step 1: Add Tests for Current Behavior
**Files:**
- `src/tests/...` - Add comprehensive tests

**Changes:**
- Test all current behavior
- Ensure 100% coverage of what's being refactored

**Why:** Safety net - tests lock in current behavior

### Step 2: Extract <Component>
**Files:**
- `src/<new_file>.py` - Create new module

**Changes:**
- Extract functionality
- Keep interface same
- No behavior change

**Testing:**
- All existing tests still pass

### Step 3: Refactor Internals
**Files:**
- `src/<new_file>.py` - Improve internals

**Changes:**
- Clean up implementation
- Still same interface

**Testing:**
- All tests still pass

### Step 4: Update Callers (if needed)
**Files:**
- Files that use refactored code

**Changes:**
- Update imports
- Update calls if interface changed

### Verification
- All tests pass
- No behavior changes
- Code is cleaner/more maintainable

Examples

Example 1: New feature plan

Context: Add user profile page with avatar upload

Plan:
1. Backend - Add avatar storage endpoint
   - Files: web_server.py, storage.py
   - Accept file upload, validate size/type
   - Store in data/avatars/
   - Test: curl upload test

2. Backend - Add profile retrieval endpoint
   - Files: web_server.py
   - Return user data + avatar URL
   - Test: API response format

3. Frontend - Create ProfilePage component
   - Files: frontend/src/components/ProfilePage.vue
   - Display user info, avatar
   - Add upload button
   - Test: Manual browser testing

4. Frontend - Wire up upload
   - Handle file selection
   - Call API
   - Show upload progress
   - Update avatar on success
   - Test: Full upload flow

Example 2: Bug fix plan

Context: Fix null pointer when login with empty email

Plan:
1. Add failing test
   - Files: test_auth.py
   - Test login with empty email
   - Verify it currently fails with null pointer

2. Add validation
   - Files: web_server.py (login endpoint)
   - Check email is not empty before processing
   - Return 400 error if empty
   - Test: Run test - should pass now

3. Add frontend validation
   - Files: frontend/src/components/LoginForm.vue
   - Disable submit if email empty
   - Show validation message
   - Test: Try to submit with empty email

Example 3: Complex feature plan

Context: Add real-time session collaboration (multiple users in one session)

Plan - HIGH LEVEL:
1. Design phase (not implementation yet)
   - Research: How to handle concurrent edits?
   - Research: Conflict resolution strategy?
   - Research: WebSocket message format?
   - Decision: Document chosen approach

2. Data model phase
   - Add session membership concept
   - Add presence tracking
   - Add edit locking or OT/CRDT

3. Backend phase
   - WebSocket broadcast to session members
   - Handle join/leave
   - Conflict resolution

4. Frontend phase
   - Show active users
   - Merge incoming edits
   - Show who's typing

Note: This is MVP roadmap. Each phase needs detailed plan when ready.