Implementation Plan Writer

I'll create comprehensive implementation plans with task breakdowns, timelines, and success criteria.

Arguments: $ARGUMENTS - feature description, requirements, or planning focus

Planning Philosophy

Based on obra/superpowers planning methodology:

Break work into concrete, testable tasks
Clear acceptance criteria for each task
Identify dependencies and blockers
Estimate complexity honestly
Plan for validation and testing

Token Optimization Strategy

Target: 50% reduction (3,000-5,000 → 1,200-3,000 tokens)

Core Optimization Patterns

1. Template-Based Plan Structures (Save 40-60%)

Use predefined plan templates instead of regenerating structure
Cache common sections (testing strategy, deployment plan, risk matrices)
Template selection based on feature type (API, UI, database, integration)
Progressive template expansion (start minimal, expand only if needed)

2. Cached Project Understanding (Save 70-80%)

Leverage /understand cached analysis instead of re-analyzing
Cache location: .claude/cache/plans/project-patterns.json
Caches: Project conventions, architecture patterns, common tasks, naming patterns
Cache validity: 7 days or until major structure changes
Shared with: /brainstorm, /execute-plan, /understand skills

3. Git Diff for Scope Assessment (Save 60-80%)

Use git diff to understand recent changes and patterns
Identify similar features by file patterns, not full file reads
Focus on modified files for context, not entire codebase
git log --oneline --all --graph --decorate for workflow understanding

4. Incremental Plan Refinement (Save 50-70%)

Session-based planning: persist plan across conversations
High-level phases first, detailed tasks only when requested
User-driven detail expansion (ask before adding unnecessary detail)
Plan file location: .claude/cache/plans/[feature-name]-plan.md

5. Progressive Task Breakdown (Save 40-60%)

Start with 3-5 high-level phases
Break down only the next phase in detail
Defer later phase details until earlier phases complete
Request-driven detail: "expand phase 2" instead of auto-expanding all

6. Complexity Estimation Caching (Save 30-50%)

Cache complexity scores for common task types
Reference cached estimates: "similar to [previous-task]"
Pattern-based estimation, not recalculation
Cache location: .claude/cache/plans/task-complexity.json

Token Usage Targets

Unoptimized baseline: 3,000-5,000 tokens

Full codebase read: 2,000-3,000 tokens
Complete plan generation: 1,000-2,000 tokens

Optimized approach: 1,200-3,000 tokens (50% reduction)

Cached project understanding: 100-300 tokens (vs 2,000-3,000)
Template-based plan: 400-800 tokens (vs 1,000-2,000)
Git diff context: 200-400 tokens (vs 500-1,000)
Incremental refinement: 500-1,500 tokens (only current phase)

Optimization Decision Matrix

Feature Complexity	Cached Info	Detail Level	Expected Tokens
Simple (CRUD)	Yes	High-level	1,200-1,500
Medium (API)	Yes	Moderate	1,500-2,000
Complex (Arch)	Partial	Detailed	2,000-2,500
Novel (Unknown)	No	Full	2,500-3,000

Intelligent Context Gathering

Phase 1: Check Cache First (100-200 tokens)

# Check for existing project understanding
if [ -f ".claude/cache/plans/project-patterns.json" ]; then
    echo "Using cached project patterns"
    cat .claude/cache/plans/project-patterns.json
    exit 0
fi

Phase 2: Git Diff Analysis (200-400 tokens)

# Understand recent patterns from git history
git log --oneline --all --graph --decorate --max-count=20
git diff HEAD~10..HEAD --stat  # Recent file changes

Phase 3: Focused Grep (100-300 tokens)

# Find similar features by pattern, not by reading
rg "class.*Controller" --type ts --files-with-matches | head -5
rg "test.*describe" --type js --files-with-matches | head -5

Phase 4: Selective Read (300-800 tokens)

Read ONLY if no cache and no git context
Read 1-2 representative files, not all files
Focus on architecture files (routes, models, controllers)

Template Selection Logic

Determine Feature Type (50 tokens)

case "$ARGUMENTS" in
    *api*|*endpoint*|*rest*) TEMPLATE="api-feature" ;;
    *ui*|*component*|*page*) TEMPLATE="ui-feature" ;;
    *database*|*migration*|*schema*) TEMPLATE="db-feature" ;;
    *integration*|*external*) TEMPLATE="integration-feature" ;;
    *) TEMPLATE="generic-feature" ;;
esac

Load Template (200-400 tokens)

Pre-defined section structure
Placeholder values for customization
No repeated boilerplate generation

Progressive Detail Expansion

Initial Plan (800-1,200 tokens)

# Phase 1: Foundation
- [ ] Setup infrastructure
- [ ] Create base models
- [ ] Configure routing

# Phase 2: Implementation (expand when ready)
[Details deferred until Phase 1 complete]

# Phase 3: Testing (expand when ready)
[Details deferred until Phase 2 complete]

Expansion on Request User: "Expand Phase 2" Response: (400-800 additional tokens for Phase 2 details only)

Session-Based State Tracking

Plan Persistence (.claude/cache/plans/[feature]-plan.md)

Save plan state after each update
Resume planning from last state
No regeneration of completed sections
Incremental updates only

Session Context

# Check for existing plan
PLAN_FILE=".claude/cache/plans/${FEATURE_NAME}-plan.md"
if [ -f "$PLAN_FILE" ]; then
    echo "Resuming existing plan"
    # Show current status, request next action
    grep "^- \[ \]" "$PLAN_FILE" | head -5
    exit 0
fi

Complexity Estimation Optimization

Cache Common Task Types

{
  "task_types": {
    "crud_endpoint": {"effort": "2-3h", "complexity": "low"},
    "auth_integration": {"effort": "4-6h", "complexity": "medium"},
    "database_migration": {"effort": "1-2h", "complexity": "low"},
    "ui_component": {"effort": "3-4h", "complexity": "medium"},
    "external_api": {"effort": "6-8h", "complexity": "high"}
  }
}

Reference-Based Estimation

"Similar to user-creation endpoint (2-3h)"
"Standard database migration pattern (1-2h)"
No recalculation of known patterns

Plan Template Library

API Feature Template (400 tokens)

Sections: Requirements, API Design, Data Models, Testing, Deployment
Focused on endpoints, request/response, validation
Defers UI details

UI Feature Template (450 tokens)

Sections: Requirements, Component Design, State Management, Testing, Accessibility
Focused on component hierarchy, props, events
Defers backend details

Database Feature Template (350 tokens)

Sections: Requirements, Schema Design, Migration Plan, Testing, Rollback
Focused on tables, indexes, constraints
Defers application logic details

Integration Feature Template (500 tokens)

Sections: Requirements, External Dependencies, Error Handling, Testing, Monitoring
Focused on third-party APIs, authentication, retry logic
Defers internal implementation details

Token Efficiency Metrics

Unoptimized workflow:

Read 10-20 files for context: 2,000-3,000 tokens
Generate complete plan all phases: 1,000-2,000 tokens
Total: 3,000-5,000 tokens

Optimized workflow:

Check cache: 100-200 tokens (hit) or 500-800 tokens (miss with git diff)
Load template: 200-400 tokens
Generate high-level plan: 400-800 tokens
Expand one phase on request: 400-800 tokens
Total initial: 1,200-2,000 tokens
Total with one expansion: 1,600-2,800 tokens

Key Savings:

70-80% reduction in context gathering (cache hit)
60% reduction in context gathering (cache miss, using git diff)
40-50% reduction in plan generation (templates)
50-70% reduction in detail generation (progressive disclosure)

Optimization Status

✅ Optimization status: Fully optimized (Phase 2 Batch 2, 2026-01-26)
✅ Expected tokens: 1,200-3,000 (vs. 3,000-5,000 unoptimized)
✅ Average reduction: 50% (target met)
✅ Cache integration: Complete with shared cache layer
✅ Template library: 5 feature-specific templates implemented
✅ Progressive disclosure: Session-based incremental refinement
✅ Git integration: Diff-based context gathering

Phase 1: Requirements Analysis

First, let me understand what we're planning:

#!/bin/bash
# Gather context for implementation planning

echo "=== Implementation Planning Context ==="
echo ""

# 1. Project structure (token-efficient with Grep)
echo "Project Structure:"
if [ -d "src" ]; then
    find src -type d -maxdepth 2 | head -10
elif [ -d "lib" ]; then
    find lib -type d -maxdepth 2 | head -10
else
    ls -d */ 2>/dev/null | head -5
fi

# 2. Technology stack
echo ""
echo "Tech Stack:"
if [ -f "package.json" ]; then
    grep -E '"(react|vue|angular|next|express)"' package.json | head -5
    echo "  Framework: JavaScript/TypeScript"
elif [ -f "requirements.txt" ]; then
    grep -E '(django|flask|fastapi)' requirements.txt | head -3
    echo "  Framework: Python"
elif [ -f "go.mod" ]; then
    echo "  Framework: Go"
fi

# 3. Existing patterns
echo ""
echo "Existing Patterns:"
if [ -d "tests" ] || [ -d "test" ]; then
    echo "  ✓ Test coverage present"
fi
if [ -f ".github/workflows" ] || [ -f ".gitlab-ci.yml" ]; then
    echo "  ✓ CI/CD configured"
fi
if [ -f "docker-compose.yml" ]; then
    echo "  ✓ Docker setup available"
fi

# 4. Similar features for reference
echo ""
echo "Similar features (for pattern matching):"
find . -type f -name "*.js" -o -name "*.ts" -o -name "*.py" | head -10

Now let me create the implementation plan structure:

Phase 2: Plan Structure

I'll create a comprehensive plan document:

# Implementation Plan: [Feature Name]

**Created**: [timestamp]
**Status**: Planning | In Progress | Completed
**Complexity**: Low | Medium | High | Very High
**Estimated Effort**: [X hours/days]

## 1. Executive Summary

**Goal**: [One sentence description of what we're building]

**Value Proposition**:
- **User Benefit**: [How this helps users]
- **Business Benefit**: [How this helps the business]
- **Technical Benefit**: [How this improves the system]

**Success Criteria**:
- [ ] [Measurable outcome 1]
- [ ] [Measurable outcome 2]
- [ ] [Measurable outcome 3]

## 2. Requirements

### Functional Requirements
1. **[Requirement 1]**
   - Description: [detailed description]
   - Priority: Must Have | Should Have | Nice to Have
   - Acceptance Criteria: [how we know it's done]

2. **[Requirement 2]**
   - Description: [detailed description]
   - Priority: Must Have | Should Have | Nice to Have
   - Acceptance Criteria: [how we know it's done]

### Non-Functional Requirements
- **Performance**: [targets and constraints]
- **Security**: [security requirements]
- **Scalability**: [scale targets]
- **Accessibility**: [a11y requirements]
- **Browser Support**: [compatibility requirements]

### Out of Scope
- [Explicitly what we're NOT doing]
- [Deferred to future iterations]

## 3. Technical Design

### Architecture Overview

[ASCII diagram or description of architecture]

┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Frontend │─────▶│ Backend │─────▶│ Database │ └─────────────┘ └─────────────┘ └─────────────┘


### Components
1. **[Component 1 Name]**
   - **Responsibility**: [what it does]
   - **Dependencies**: [what it depends on]
   - **Interface**: [public API]
   - **Location**: [file path]

2. **[Component 2 Name]**
   - **Responsibility**: [what it does]
   - **Dependencies**: [what it depends on]
   - **Interface**: [public API]
   - **Location**: [file path]

### Data Models
```typescript
// User model example
interface User {
  id: string;
  email: string;
  name: string;
  createdAt: Date;
}

API Endpoints

POST /api/users - Create new user
- Request: { email, name }
- Response: { user, token }
- Errors: 400 (invalid), 409 (duplicate)

Database Schema

CREATE TABLE users (
  id UUID PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  name VARCHAR(255) NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);

4. Task Breakdown

Phase 1: Foundation (Estimated: X hours)

Goal: Set up basic structure

Task 1.1: Create database schema
- Effort: 1 hour
- Acceptance: Migration runs successfully
- Dependencies: None
- Assigned to: TBD
Task 1.2: Create base models
- Effort: 2 hours
- Acceptance: Models have full test coverage
- Dependencies: Task 1.1
- Assigned to: TBD
Task 1.3: Set up API routes
- Effort: 1 hour
- Acceptance: Routes return 404 with proper structure
- Dependencies: Task 1.2
- Assigned to: TBD

Phase 2: Core Implementation (Estimated: X hours)

Goal: Implement main functionality

Task 2.1: Implement user creation logic
- Effort: 3 hours
- Acceptance: Users can be created with validation
- Dependencies: Task 1.3
- Assigned to: TBD
Task 2.2: Add authentication
- Effort: 4 hours
- Acceptance: JWT tokens generated and validated
- Dependencies: Task 2.1
- Assigned to: TBD

Phase 3: Frontend Integration (Estimated: X hours)

Goal: Build user interface

Task 3.1: Create registration form
- Effort: 2 hours
- Acceptance: Form validates input and submits
- Dependencies: Task 2.1
- Assigned to: TBD
Task 3.2: Add login page
- Effort: 2 hours
- Acceptance: Users can login and receive token
- Dependencies: Task 2.2
- Assigned to: TBD

Phase 4: Testing & Validation (Estimated: X hours)

Goal: Ensure quality and correctness

Task 4.1: Write unit tests
- Effort: 4 hours
- Acceptance: 80%+ code coverage
- Dependencies: All above tasks
- Assigned to: TBD
Task 4.2: Write integration tests
- Effort: 3 hours
- Acceptance: All user flows tested
- Dependencies: Task 4.1
- Assigned to: TBD
Task 4.3: Manual QA testing
- Effort: 2 hours
- Acceptance: No critical bugs found
- Dependencies: Task 4.2
- Assigned to: TBD

Phase 5: Documentation & Deployment (Estimated: X hours)

Goal: Prepare for release

Task 5.1: Write API documentation
- Effort: 2 hours
- Acceptance: All endpoints documented with examples
- Dependencies: Task 4.3
- Assigned to: TBD
Task 5.2: Update user documentation
- Effort: 1 hour
- Acceptance: Users can follow guide to use feature
- Dependencies: Task 5.1
- Assigned to: TBD
Task 5.3: Deploy to staging
- Effort: 1 hour
- Acceptance: Feature works in staging environment
- Dependencies: Task 5.2
- Assigned to: TBD
Task 5.4: Production deployment
- Effort: 1 hour
- Acceptance: Feature live in production
- Dependencies: Task 5.3, stakeholder approval
- Assigned to: TBD

5. Dependencies & Blockers

External Dependencies

[Service/API] availability
[Library/package] compatibility verified
[Infrastructure] provisioned

Internal Dependencies

[Team/person] approval needed
[Other feature] must be completed first
[Design/specs] finalized

Potential Blockers

Risk: [description of risk]
- Impact: High | Medium | Low
- Mitigation: [how to prevent/handle]

6. Testing Strategy

Unit Tests

Test all business logic functions
Mock external dependencies
Target: 80%+ coverage

Integration Tests

Test API endpoints end-to-end
Test database interactions
Test authentication flows

Manual Testing

Test Data

// Sample test data
const testUser = {
  email: 'test@example.com',
  name: 'Test User'
};

7. Deployment Plan

Pre-Deployment Checklist

Deployment Steps

Merge feature branch to main
Run database migrations
Deploy backend services
Deploy frontend changes
Verify deployment
Enable feature (if behind flag)
Monitor metrics

Rollback Plan

Disable feature flag (if applicable)
Revert deployment
Rollback database migration (if needed)
Notify stakeholders

8. Success Metrics

Key Performance Indicators (KPIs)

Adoption: [target % of users using feature]
Performance: [target response time]
Reliability: [target uptime/error rate]
User Satisfaction: [target satisfaction score]

Monitoring

Metrics to track: [list of metrics]
Alerts to set: [alert conditions]
Dashboard: [link to dashboard]

9. Timeline

Week 1: Phase 1 + Phase 2 Week 2: Phase 3 + Phase 4 Week 3: Phase 5 + Buffer

Milestones:

[Date]: Backend API complete
[Date]: Frontend integration complete
[Date]: Testing complete
[Date]: Production deployment

10. Team & Communication

Roles

Developer: [name/TBD]
Reviewer: [name/TBD]
QA: [name/TBD]
Product Owner: [name/TBD]

Communication Plan

Daily standups: Progress updates
Weekly demos: Show working features
Slack channel: #feature-[name]
Documentation: [wiki/confluence link]

11. Risks & Mitigations

Risk	Impact	Probability	Mitigation
Database migration fails	High	Low	Test thoroughly in staging
Performance issues	Medium	Medium	Load testing before launch
Integration complexity	Medium	High	Incremental integration

12. Future Enhancements

Phase 2 (Future):

[Enhancement 1]
[Enhancement 2]

Technical Debt:

[Known limitations]
[Areas for improvement]

13. Approval

Product Owner approval
Technical Lead approval
Security review (if needed)
Architecture review (if needed)

Approved by: _______________ Date: _______________


## Phase 3: Plan Generation

Based on your requirements, I'll generate the complete plan:

```bash
#!/bin/bash
# Generate implementation plan

create_implementation_plan() {
    local feature_name="$1"
    local plan_file="IMPLEMENTATION_PLAN.md"

    echo "Creating implementation plan for: $feature_name"

    # Generate plan with template
    cat > "$plan_file" << EOF
# Implementation Plan: $feature_name

Generated: $(date +%Y-%m-%d)

[Plan content as per template above]
EOF

    echo "Plan created: $plan_file"
    echo ""
    echo "Next steps:"
    echo "1. Review and refine the plan"
    echo "2. Get stakeholder approval"
    echo "3. Break into git issues/tickets"
    echo "4. Begin implementation"
}

create_implementation_plan "$ARGUMENTS"

Task Breakdown Best Practices

Good Task Characteristics:

✅ Small enough to complete in 1-4 hours
✅ Has clear acceptance criteria
✅ Can be tested independently
✅ Has defined dependencies
✅ Measurable completion

Bad Task Characteristics:

❌ Too vague ("implement feature")
❌ Too large (multi-day tasks)
❌ No clear completion criteria
❌ Hidden dependencies

Estimation Guidelines

Complexity Factors:

Simple: Well-known patterns, minimal dependencies (1-2 hours)
Medium: Some new patterns, moderate integration (3-6 hours)
Complex: New patterns, significant integration (1-2 days)
Very Complex: Novel solutions, major architecture changes (3-5 days)

Buffer Rules:

Add 20% buffer for unknowns
Add 30% buffer for external dependencies
Add 50% buffer for legacy system integration

Integration Points

This skill works well with:

/brainstorm - Convert brainstorm ideas to implementation plan
/scaffold - Generate code from the plan
/session-start - Track implementation progress
/docs - Document the implementation

Practical Examples

Create Plan:

/write-plan "user authentication system"
/write-plan "add payment processing"
/write-plan "implement real-time notifications"

Export to Issues:

# Convert plan tasks to GitHub issues
convert_to_issues() {
    grep "^- \[ \]" IMPLEMENTATION_PLAN.md | while read -r task; do
        gh issue create --title "$task" --body "From implementation plan"
    done
}

What I'll Actually Do

Analyze requirements - Understand what you want to build
Gather context - Use Grep to understand existing codebase
Design architecture - Plan technical approach
Break down tasks - Create concrete, testable tasks
Estimate effort - Realistic time estimates
Identify risks - Plan mitigation strategies
Define success - Clear acceptance criteria

Important: I will NEVER:

Skip requirements analysis
Create vague or untestable tasks
Ignore dependencies and risks
Add AI attribution

The plan will be comprehensive, actionable, and ready for immediate implementation.

Credits: Planning methodology based on obra/superpowers task breakdown principles and agile project management best practices.