implementation-planner

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.