planning-implementation

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.