planning-implementation

name	Planning Implementation
description	Create structured implementation plans before coding. Use when breaking down complex features, refactors, or system changes. Validates requirements, analyzes codebase impact, and produces actionable task breakdowns with identified dependencies and risks.

Planning Implementation

When to Use

• Creating structured approach BEFORE implementing
• Breaking down complex work into steps
• Designing architecture for new features
• Planning refactoring or system changes
• Analyzing impact before major changes

Core Steps

1. Clarify Requirements (if ambiguous)

Ask discovery questions (5-7 max):

1. Happy Path: Describe successful scenario step-by-step
2. Edge Cases: Empty state, invalid input, errors, large datasets?
3. Scope Boundaries: What's explicitly OUT of scope?
4. Performance: Instant (<100ms), fast (<1s), or eventual (loading)?
5. Integration: Interactions with existing features, APIs, auth?

Feature-specific questions:

• Auth: Credentials approach, session duration, failure handling?
• CRUD: Validation rules, concurrent edits, delete behavior?
• Search: Scope, match type, timing (live/submit)?
• Real-time: Update mechanism (polling/WebSocket), frequency, offline?

Generate inferences with confidence levels:

[INFER-HIGH]: JWT in httpOnly cookies (security best practice)
[INFER-MEDIUM]: Debounced search 300ms (balance UX + performance)
[INFER-LOW]: Max 100 results per page (prevent UI overload)

Get approval before proceeding if requirements are unclear.

2. Investigation Phase (CRITICAL)

Read project documentation first:

• docs/product-requirements.md - project goals, existing features (F-##)
• docs/feature-spec/F-##-*.md - technical details
• docs/system-design.md - architecture patterns
• docs/api-contracts.yaml - API standards
• docs/design-spec.md - UI patterns

Investigation checklist:

• ALL affected files identified (complete impact analysis)
• Current system architecture understood
• All dependencies and integration points mapped
• Existing patterns and conventions documented
• Data models and schemas reviewed
• Current data flows traced
• ALL call sites found (especially for refactors)
• Test impact assessed
• Breaking changes identified

Investigation approach (choose based on scope):

Small/contained features: Use direct tools (Grep, Glob, Read) for focused analysis.

Large/complex changes or refactors: Delegate to Explore agents in parallel for comprehensive impact analysis:

• Find ALL affected files across codebase
• Identify every usage, call site, and dependency
• Map integration points and data flows
• Discover existing patterns to follow
• Identify breaking changes and ripple effects

Parallel investigation patterns:

Pattern 1: Full-stack feature/refactor

• Agent 1: Backend analysis (services, APIs, models, call sites, integrations)
• Agent 2: Frontend analysis (components, state, API clients, dependencies)
• Agent 3: Data layer (schema, queries, migrations, integrity)

Pattern 2: Architecture + integration

• Agent 1: Current system (organization, stack, patterns, boundaries)
• Agent 2: Integration needs (external APIs, auth, database, libraries)

Pattern 3: Single domain (contained feature)

• Agent 1: Complete domain analysis (ALL files, call sites, dependencies, imports, tests, config)

3. Create Implementation Plan

Write plan to docs/plans/[feature-slug]/plan.md

Use templates for structure:

• Small: ~/.claude/file-templates/plan.quick.template.md
• Medium: ~/.claude/file-templates/plan.template.md
• Large: ~/.claude/file-templates/plan.comprehensive.template.md

Plan template structure:

# Implementation Plan: [Feature Name]

## Overview
[Brief description of what we're building and why]

## Requirements Summary
[Key requirements from clarification phase]

## Investigation Artifacts
[Link agent responses or summarize findings]

## Tasks

### Task 1: [Name]
**What:** [What needs to be done]
**Files:** [Files to create/modify]
**Dependencies:** None / Requires Task X

### Task 2: [Name]
**What:** [What needs to be done]
**Files:** [Files to create/modify]
**Dependencies:** Requires Task 1

## Parallelization Opportunities
[Identify groups of independent tasks]

## Integration Points
- [External systems or APIs]
- [Existing features that interact]

## Testing Strategy
- [Key test scenarios]
- [Coverage requirements]

## Risks
- [Potential issues or unknowns]
- [Breaking changes]

## Key Decisions
- [Important technical decisions with reasoning]

Plan size: 3-6 main tasks (break complex work into manageable chunks)

Identify parallelization:

## Batch 1 (Parallel - no shared dependencies)
- Task 1: Backend API endpoint
- Task 2: Frontend component
- Task 3: Database migration

## Batch 2 (Sequential - depends on Batch 1)
- Task 4: Integration layer
- Task 5: Tests

Default to sequential unless clear benefit to parallel execution.

4. Link Plan to Project Docs (if applicable)

Update project documentation using available commands:

Before implementation:

• Validate current documentation state
• Add new features if plan introduces them (creates F-## IDs, entries)
• Update requirements if plan changes scope, metrics, or risks

After implementation:

• Add user stories linked to features
• Add new API endpoints
• Update design if UI components or patterns were added

Documentation scope:

• docs/product-requirements.yaml
• docs/feature-specs/F-##-[slug].yaml
• docs/user-stories/US-###-[slug].yaml
• docs/api-contracts.yaml
• docs/system-design.yaml
• docs/data-plan.yaml
• docs/design-spec.yaml

5. Present Plan for Approval

Share:

• Key tasks (3-6 items)
• Major integration points
• Any breaking changes
• Parallelization opportunities

Get explicit approval before implementation.

Investigation Checklist by Category

For new features:

• Read existing feature specs for patterns
• Check system design for architecture guidance
• Review API contracts for naming conventions
• Examine similar features in codebase
• Identify all affected domains

For refactors:

• Find ALL files importing/using the code
• Identify ALL call sites (not just obvious ones)
• Locate ALL tests
• Check configuration files
• Find documentation references
• Identify ripple effects

For integrations:

• Review existing integration patterns
• Check authentication/authorization approach
• Understand error handling conventions
• Identify shared utilities
• Map external API dependencies

Common Patterns

Quick Planning (Small changes)

# Plan: [Feature Name]

## Goal
[What we're building and why]

## Tasks
1. [Task] - [Files] - [Dependencies]
2. [Task] - [Files] - [Dependencies]
3. [Task] - [Files] - [Dependencies]

## Key Decisions
- [Important technical decision with reasoning]

## Risks
- [Potential issues]

Investigation Tools

Direct investigation:

• Read - Examine existing code and docs
• Grep - Find all usages, imports, call sites
• Glob - Find files by pattern

Comprehensive investigation (refactors, large features):

# Find all imports
grep -r "import.*ComponentName" --include="*.tsx"

# Find all usages
grep -r "ComponentName" --include="*.ts"

# Find tests
grep -r "describe.*ComponentName" --include="*.test.ts"

For parallel analysis:

• Delegate Explore agents for pattern discovery
• Monitor agent responses from agent-responses/ directory
• Link investigation artifacts in final plan

Example: Planning a New API Feature

Step 1: Clarify

• Happy path: User creates X, receives Y response
• Edge cases: Invalid input, duplicate keys, concurrent requests
• Performance: Response time <200ms
• Integration: Requires authentication, updates cache

Step 2: Investigate

• Read docs/api-contracts.yaml for naming/structure patterns
• Search for similar endpoints (e.g., CRUD patterns)
• Find authentication middleware usage
• Check cache invalidation patterns
• Identify all affected services

Step 3: Plan

• Task 1: Add API schema to contracts
• Task 2: Implement controller/handler
• Task 3: Add service layer logic
• Task 4: Implement persistence
• Task 5: Add cache invalidation
• Task 6: Write tests

Step 4: Approval

Share plan with stakeholders, get sign-off.

Step 5: Handoff

Pass plan + investigation results to implementation agents.

Key Principles

• Nothing is left to assumptions. Thorough investigation is mandatory.
• Default to agent-based impact analysis for refactors and cross-cutting changes.
• Use direct tools for small, contained features to stay efficient.
• Breaking changes must be identified early and communicated clearly.
• Plans enable parallel execution when dependencies are clear.
• Approval gates prevent rework. Always get sign-off before implementation.