Planning

Planning

Create detailed technical implementation plans through research, codebase analysis, solution design, and comprehensive documentation.

When to Use

Use this skill when:

• Planning new feature implementations
• Architecting system designs
• Evaluating technical approaches
• Creating implementation roadmaps
• Breaking down complex requirements
• Assessing technical trade-offs

Core Responsibilities & Rules

Always honoring YAGNI, KISS, and DRY principles. Be honest, be brutal, straight to the point, and be concise.

1. Research & Analysis

Load: references/research-phase.md Skip if: Provided with researcher reports

2. Codebase Understanding

Load: references/codebase-understanding.md Skip if: Provided with scout reports

3. Solution Design

Load: references/solution-design.md

4. Plan Creation & Organization

Load: references/plan-organization.md

5. Task Breakdown & Output Standards

Load: references/output-standards.md

Workflow Process

1. Initial Analysis → Read codebase docs, understand context 2. Research Phase → Spawn researchers, investigate approaches 3. Synthesis → Analyze reports, identify optimal solution 4. Design Phase → Create architecture, implementation design 5. Plan Documentation → Write comprehensive plan 6. Review & Refine → Ensure completeness, clarity, actionability

Output Requirements

• DO NOT implement code - only create plans
• Respond with plan file path and summary
• Ensure self-contained plans with necessary context
• Include code snippets/pseudocode when clarifying
• Provide multiple options with trade-offs when appropriate

Plan Directory Structure

plans/
└── YYYYMMDD-HHmm-plan-name/
    ├── research/
    │   ├── researcher-XX-report.md
    │   └── ...
    ├── reports/
    │   ├── XX-report.md
    │   └── ...
    ├── scout/
    │   ├── scout-XX-report.md
    │   └── ...
    ├── plan.md
    ├── phase-XX-phase-name-here.md
    └── ...

Quality Standards

• Be thorough and specific
• Consider long-term maintainability
• Research thoroughly when uncertain
• Address security and performance concerns
• Make plans detailed enough for junior developers
• Validate against existing codebase patterns

Remember: Plan quality determines implementation success. Be comprehensive and consider all solution aspects.

Codebase Understanding Phase

When to skip: If provided with scout reports, skip this phase.

Core Activities

Parallel Scout Agents

• Use /scout:ext (preferred) or /scout (fallback) slash command to search the codebase for files needed to complete the task
• Each scout locates files needed for specific task aspects
• Wait for all scout agents to report back before analysis
• Efficient for finding relevant code across large codebases

Essential Documentation Review

ALWAYS read these files first:

1. `./docs/codebase-summary.md`

• Project structure and current status
• High-level architecture overview
• Component relationships

2. `./docs/code-standards.md`

• Coding conventions and standards
• Language-specific patterns
• Naming conventions

3. `./docs/design-guidelines.md` (if exists)

• Design system guidelines
• Branding and UI/UX conventions
• Component library usage

Environment Analysis

• Review development environment setup
• Analyze dotenv files and configuration
• Identify required dependencies
• Understand build and deployment processes

Pattern Recognition

• Study existing patterns in codebase
• Identify conventions and architectural decisions
• Note consistency in implementation approaches
• Understand error handling patterns

Integration Planning

• Identify how new features integrate with existing architecture
• Map dependencies between components
• Understand data flow and state management
• Consider backward compatibility

Best Practices

• Start with documentation before diving into code
• Use scouts for targeted file discovery
• Document patterns found for consistency
• Note any inconsistencies or technical debt
• Consider impact on existing features

Output Standards & Quality

Task Breakdown

• Transform complex requirements into manageable, actionable tasks
• Each task independently executable with clear dependencies
• Prioritize by dependencies, risk, business value
• Eliminate ambiguity in instructions
• Include specific file paths for all modifications
• Provide clear acceptance criteria per task

File Management

List affected files with:

• Full paths (not relative)
• Action type (modify/create/delete)
• Brief change description
• Dependencies on other changes

Workflow Process

1. Initial Analysis → Read docs, understand context 2. Research Phase → Spawn researchers in parallel, investigate approaches 3. Synthesis → Analyze reports, identify optimal solution 4. Design Phase → Create architecture, implementation design 5. Plan Documentation → Write comprehensive plan in Markdown 6. Review & Refine → Ensure completeness, clarity, actionability

Output Requirements

What Planners Do

• Create plans ONLY (no implementation)
• Provide plan file path and summary
• Self-contained plans with necessary context
• Code snippets/pseudocode when clarifying
• Multiple options with trade-offs when appropriate

Writing Style

IMPORTANT: Sacrifice grammar for concision

• Focus clarity over eloquence
• Use bullets and lists
• Short sentences
• Remove unnecessary words
• Prioritize actionable info

Unresolved Questions

IMPORTANT: List unresolved questions at end

• Questions needing clarification
• Technical decisions requiring input
• Unknowns impacting implementation
• Trade-offs requiring business decisions

Quality Standards

Thoroughness

• Thorough and specific in research/planning
• Consider edge cases, failure modes
• Think through entire user journey
• Document all assumptions

Maintainability

• Consider long-term maintainability
• Design for future modifications
• Document decision rationale
• Avoid over-engineering

Research Depth

• When uncertain, research more
• Multiple options with clear trade-offs
• Validate against best practices
• Consider industry standards

Security & Performance

• Address all security concerns
• Identify performance implications
• Plan for scalability
• Consider resource constraints

Implementability

• Detailed enough for junior developers
• Validate against existing patterns
• Ensure codebase standards consistency
• Provide clear examples

Remember: Plan quality determines implementation success. Be comprehensive, consider all solution aspects.

Plan Creation & Organization

Directory Structure

Plan Location

Save plans in ./plans directory with timestamp and descriptive name.

Format: plans/YYYYMMDD-HHmm-your-plan-name/

Example: plans/20251101-1505-authentication-and-profile-implementation/

File Organization

plans/
├── 20251101-1505-authentication-and-profile-implementation/
    ├── research/
    │   ├── researcher-XX-report.md
    │   └── ...
│   ├── reports/
│   │   ├── scout-report.md
│   │   ├── researcher-report.md
│   │   └── ...
│   ├── plan.md                                # Overview access point
│   ├── phase-01-setup-environment.md          # Setup environment
│   ├── phase-02-implement-database.md         # Database models
│   ├── phase-03-implement-api-endpoints.md    # API endpoints
│   ├── phase-04-implement-ui-components.md    # UI components
│   ├── phase-05-implement-authentication.md   # Auth & authorization
│   ├── phase-06-implement-profile.md          # Profile page
│   ├── phase-07-write-tests.md                # Tests
│   ├── phase-08-run-tests.md                  # Test execution
│   ├── phase-09-code-review.md                # Code review
│   ├── phase-10-project-management.md         # Project management
│   ├── phase-11-onboarding.md                 # Onboarding
│   └── phase-12-final-report.md               # Final report
└── ...

File Structure

Overview Plan (plan.md)

• Keep generic and under 80 lines
• List each phase with status/progress
• Link to detailed phase files
• High-level timeline
• Key dependencies

Phase Files (phase-XX-name.md)

Each phase file should contain:

Context Links

• Links to related reports, files, documentation

Overview

• Date and priority
• Current status
• Brief description

Key Insights

• Important findings from research
• Critical considerations

Requirements

• Functional requirements
• Non-functional requirements

Architecture

• System design
• Component interactions
• Data flow

Related Code Files

• List of files to modify
• List of files to create
• List of files to delete

Implementation Steps

• Detailed, numbered steps
• Specific instructions

Todo List

• Checkbox list for tracking

Success Criteria

• Definition of done
• Validation methods

Risk Assessment

• Potential issues
• Mitigation strategies

Security Considerations

• Auth/authorization
• Data protection

Next Steps

• Dependencies
• Follow-up tasks

Research & Analysis Phase

When to skip: If provided with researcher reports, skip this phase.

Core Activities

Parallel Researcher Agents

• Spawn multiple researcher agents in parallel to investigate different approaches
• Wait for all researcher agents to report back before proceeding
• Each researcher investigates a specific aspect or approach

Sequential Thinking

• Use sequential-thinking skill for dynamic and reflective problem-solving
• Structured thinking process for complex analysis
• Enables multi-step reasoning with revision capability

Documentation Research

• Use docs-seeker skill to read and understand documentation
• Research plugins, packages, and frameworks
• Find latest technical documentation using llms.txt standard

GitHub Analysis

• Use gh command to read and analyze:
• GitHub Actions logs
• Pull requests
• Issues and discussions
• Extract relevant technical context from GitHub resources

Remote Repository Analysis

When given GitHub repository URL, generate fresh codebase summary:

# usage: 
repomix --remote <github-repo-url>
# example: 
repomix --remote https://github.com/mrgoonie/human-mcp

Debugger Delegation

• Delegate to debugger agent for root cause analysis
• Use when investigating complex issues or bugs
• Debugger agent specializes in diagnostic tasks

Best Practices

• Research breadth before depth
• Document findings for synthesis phase
• Identify multiple approaches for comparison
• Consider edge cases during research
• Note security implications early

Solution Design

Core Principles

Follow these fundamental principles:

• YAGNI (You Aren't Gonna Need It) - Don't add functionality until necessary
• KISS (Keep It Simple, Stupid) - Prefer simple solutions over complex ones
• DRY (Don't Repeat Yourself) - Avoid code duplication

Design Activities

Technical Trade-off Analysis

• Evaluate multiple approaches for each requirement
• Compare pros and cons of different solutions
• Consider short-term vs long-term implications
• Balance complexity with maintainability
• Assess development effort vs benefit
• Recommend optimal solution based on current best practices

Security Assessment

• Identify potential vulnerabilities during design phase
• Consider authentication and authorization requirements
• Assess data protection needs
• Evaluate input validation requirements
• Plan for secure configuration management
• Address OWASP Top 10 concerns
• Consider API security (rate limiting, CORS, etc.)

Performance & Scalability

• Identify potential bottlenecks early
• Consider database query optimization needs
• Plan for caching strategies
• Assess resource usage (memory, CPU, network)
• Design for horizontal/vertical scaling
• Plan for load distribution
• Consider asynchronous processing where appropriate

Edge Cases & Failure Modes

• Think through error scenarios
• Plan for network failures
• Consider partial failure handling
• Design retry and fallback mechanisms
• Plan for data consistency
• Consider race conditions
• Design for graceful degradation

Architecture Design

• Create scalable system architectures
• Design for maintainability
• Plan component interactions
• Design data flow
• Consider microservices vs monolith trade-offs
• Plan API contracts
• Design state management

Best Practices

• Document design decisions and rationale
• Consider both technical and business requirements
• Think through the entire user journey
• Plan for monitoring and observability
• Design with testing in mind
• Consider deployment and rollback strategies