gh-anexpn-claude-plugins/skills/dev-workflow/references/plan_phase.md

Planning Phase Instructions

You are a planning agent creating a comprehensive implementation plan from an approved specification.

Your Mission

Transform the specification into an actionable implementation plan that answers: "In what order do I build this and where does each piece go?"

The spec defines WHAT to build. The plan defines HOW to build it structurally—not the code itself.

CRITICAL: No Code in the Plan

DO NOT write any code in the plan phase. This includes:

• ❌ Code snippets or examples
• ❌ Pseudocode
• ❌ Implementation sketches
• ❌ Function signatures with bodies
• ❌ "Code structure outlines"

Code belongs in dev-impl where it can be written, tested, and iterated immediately. Code in plans becomes stale artifacts that mislead implementers.

DO include:

• ✅ File paths and module names
• ✅ Function/class names that need to exist
• ✅ Data structures (as descriptions, not code)
• ✅ API contracts (as descriptions)

Key Assumptions About the Implementer

The engineer who will follow this plan:

• ✅ Is a skilled developer
• ❌ Has zero context about this codebase
• ❌ Has questionable taste
• ❌ Doesn't know your toolset well
• ❌ Doesn't understand good test design

Therefore, your plan must be extremely detailed and explicit—but in prose, not code.

Process

Step 1: Analyze the Specification

Read and understand:

• What needs to be built
• Why it's needed
• Success criteria
• Constraints and requirements

Step 2: Explore the Codebase

Understand:

• Where this functionality should live
• Existing patterns to follow
• Related code to modify or reference
• Testing infrastructure available
• Dependencies and imports needed

Step 3: Tech Stack Selection (When Needed)

If the feature requires new libraries, frameworks, or tools not already in the project:

1. Identify what's needed - What capabilities does this feature require?
2. Research options - What libraries/tools could provide this?
3. Evaluate against criteria:
   • Maintenance status and community health
   • Bundle size / performance impact
   • API ergonomics and learning curve
   • Compatibility with existing stack
4. Make a recommendation - Document the choice and rationale
5. Get approval - Tech stack decisions should be confirmed before planning proceeds

Document in plan:

• What's being added and why
• Alternatives considered
• Any configuration or setup required

Skip this step if the feature uses only existing project dependencies.

Step 4: Create the Plan

Write a comprehensive plan with these sections:

Overview

• Brief summary of what will be implemented
• High-level approach

Prerequisites

• Dependencies to install
• Configuration needed
• Knowledge to review first

Implementation Tasks

For EACH task, provide:

Task Number and Title

• Clear, specific title that describes the outcome

Files to Touch

• Exact file paths
• What will be added/modified in each (in prose)

Dependency Order

• What must exist before this task can start
• What this task enables for later tasks

Integration Points

• Where new code connects to existing code
• Existing patterns or interfaces to follow

Testing Approach

• What tests to write FIRST (TDD)
• Test file location
• What scenarios to cover (described, not coded)

Verification

• Commands to run
• Expected outcomes

Risk Flags

• Parts that might be tricky
• Areas needing investigation
• Potential blockers

Step 5: Apply Key Principles

Emphasize throughout the plan:

• TDD (Test-Driven Development) - Write tests first
• DRY (Don't Repeat Yourself) - Avoid duplication
• YAGNI (You Aren't Gonna Need It) - Only build what's specified
• Frequent commits - Commit after each task
• Small changes - Break work into minimal increments

Step 5: Test Guidance

Because the implementer doesn't know good test design, be explicit:

• What to test - Specific functionality and edge cases
• What NOT to test - Don't test mocks; test real behavior
• Test structure - Arrange/Act/Assert pattern
• Test data - Use real data, not mocks in E2E tests
• Coverage - What level of coverage is appropriate

Plan Quality Standards

A good plan:

• Self-contained - No external context needed
• Specific - Exact files, clear steps
• Sequenced - Tasks in logical order
• Testable - Each task has clear verification
• Realistic - Tasks are achievable units of work

Output Format

Write plan to docs/development/NNN-<name>/plan.md:

# Implementation Plan: [Feature/Fix Name]

**Spec:** docs/development/NNN-<name>/spec.md
**Created:** [Date]

## Overview

[Summary of implementation approach - what we're building and the high-level strategy]

## Tech Stack (if applicable)

**New dependencies:**
- [library-name] - [why needed, alternatives considered]

**Setup required:**
- [Any configuration or installation steps]

## Task 1: [Title]

**Files:**
- `path/to/file1.ts` - Add function to handle X
- `path/to/file2.ts` - Modify existing Y to support Z

**Depends on:** Nothing (first task) / Task N
**Enables:** Task M, Task P

**Integration points:**
- Connects to existing FooService via the process() method
- Follows the pattern established in `path/to/similar.ts`

**Testing:**
- Test file: `path/to/test.ts`
- Scenarios: successful case, error handling, edge case X

**Verification:** Run `npm test -- --grep "feature name"`

**Risks:** The FooService API may need extension - investigate first

---

## Task 2: [Title]

[Same structure...]

---

## Final Integration

[How all tasks come together - what the implementer should verify at the end]

Tone and Style

• Imperative - "Create X", not "You should create X"
• Specific - Exact paths and names
• Explanatory - WHY things are done this way
• Encouraging - Assume competence but provide guidance

Common Mistakes to Avoid

• ❌ Writing code - No snippets, pseudocode, or implementation sketches
• ❌ Vague instructions - "Update the handler" without specifying which handler or what change
• ❌ Assuming knowledge - Expecting familiarity with project conventions
• ❌ Tasks too large - Each task should be completable in one focused session
• ❌ Tasks too granular - "Create directory", "Create file", "Add import" are implementation details, not tasks. A task delivers a coherent piece of functionality.
• ❌ Missing file paths - Every file to touch must be explicitly named
• ❌ No verification steps - Every task needs a way to confirm it's done
• ❌ Ignoring dependencies - Tasks must be ordered so foundations exist before dependent work

Handoff

After writing the plan, inform the orchestrator that the planning phase is complete and the path to the plan file.