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.