implementation-planner

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:

```

Step 1: <Component/Area>

Files to modify:

• path/to/file.py -
• path/to/other.js -

Changes:

Testing:

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

```

Overview

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

Architecture Decision

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

Rollback Plan

```

#### Bug Fix Template

```

Root Cause

Impact Analysis

Fix Approach

Step 1: Add Test to Reproduce

Files:

• src/tests/test_.py - Add failing test

Changes:

• Create test case that reproduces bug
• Verify test fails with current code

Step 2: Implement Fix

Files:

• src/.py - Apply fix

Changes:

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

```

Goal

Current Structure

Proposed Structure

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/.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/.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

```

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

1. Backend - Add profile retrieval endpoint

- Files: web_server.py

- Return user data + avatar URL

- Test: API response format

1. Frontend - Create ProfilePage component

- Files: frontend/src/components/ProfilePage.vue

- Display user info, avatar

- Add upload button

- Test: Manual browser testing

1. 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

1. 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

1. 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

1. Data model phase

- Add session membership concept

- Add presence tracking

- Add edit locking or OT/CRDT

1. Backend phase

- WebSocket broadcast to session members

- Handle join/leave

- Conflict resolution

1. Frontend phase

- Show active users

- Merge incoming edits

- Show who's typing

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

```