writing-implementation-plans

What this skill does

# Writing Implementation Plans

## Overview

Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to verify it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. Frequent commits.

Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.

**Announce at start:** "I'm using the writing-implementation-plans skill to create the implementation plan."

**Save plans to:** `docs/implementation-plans/YYYY-MM-DD-<feature-name>/phase_##.md`

## Critical: Design Plans Provide Direction, Not Code

**Design plans are intentionally high-level.** They describe components, modules, and contracts — not implementation code. This is by design.

**You MUST generate code fresh based on codebase investigation.** Do NOT copy code from the design document. Even if a design plan contains code examples (it shouldn't, but some might), treat them as illustrative only.

**Why this matters:**
- Design plans may be days or weeks old
- Codebase state changes between design and implementation
- Investigation reveals actual patterns, dependencies, and constraints
- Your code must work with the codebase as it exists NOW

**The design plan tells you WHERE you're going. Codebase investigation tells you HOW to get there from where you are.**

## Before Starting

**REQUIRED: Verify scope and codebase state**

### 1. Scope Validation

Count the phases/tasks in the design plan.

**If design plan has >8 phases:** STOP. Refuse to proceed.

Tell the user:
"This design has [N] phases, which exceeds the 8-phase limit for implementation plans. Please rerun this skill with a scope of no more than 8 phases. You can:
1. Select the first 8 phases for this implementation plan
2. Break the design into multiple implementation plans
3. Simplify the design to fit within 8 phases"

**If already implementing phases 9+:** The user should provide the previous implementation plan as context when scoping the next batch.

### 2. Review Mode Selection

**After scope validation, ask how to handle phase reviews:**

Use AskUserQuestion:
```
Question: "How would you like to review the implementation plan phases?"
Options:
  - "Write all phases to disk, I'll review afterwards"
  - "Review each phase interactively before writing"
```

**Track this choice - it affects the per-phase workflow below.**

### 3. Codebase Verification

**You MUST verify current codebase state before EACH AND EVERY PHASE. Use `codebase-investigator` to prove out your hypotheses and to ensure that current state aligns with what you want to write out.**

**YOU MUST verify current codebase state before writing ANY task.**

**DO NOT verify codebase yourself. Use codebase-investigator agent.**

**Provide the agent with design assumptions so it can report discrepancies:**

Dispatch one subagent codebase-investigator to understand testing behavior for this project.
- **DO NOT prescribe new requirements around testing. Follow how the codebase does it.**
   - For example: do NOT stipulate TDD unless you understand the scope of the problem to be a predominantly functional one OR you receive direction from a human otherwise and do not assume that mocking databases or other external dependencies is acceptable. 
- If you find problems that are difficult to test in isolation with mocks, you should surface questions to the human operator as to how they want to proceed.
- Instruct the subagent to seek out CLAUDE.md or AGENTS.md files that include details on testing behavior, logic, and methodology, and include file references for you to provide in your plan for the executor to pass to its subagents.

Dispatch a second subagent codebase-investigator (simultaneously) with:
- "The design assumes these files exist: [list with expected paths/structure from design]"
- "Verify each file exists and report any differences from these assumptions"
- "The design says [feature] is implemented in [location]. Verify this is accurate"
- "Design expects [dependency] version [X]. Check actual version installed"

**Example query to agent:**
```
Design assumptions from docs/plans/YYYY-MM-DD-feature-design.md:
- Auth service in src/services/auth.ts with login() and logout() functions
- User model in src/models/user.ts with email and password fields
- Test file at tests/services/auth.test.ts
- Uses bcrypt dependency for password hashing

Verify these assumptions and report:
1. What exists vs what design expects
2. Any structural differences (different paths, functions, exports)
3. Any missing or additional components
4. Current dependency versions
```

Review investigator findings and note any differences from design assumptions.

**Based on investigator report, NEVER write:**
- "Update `index.js` if exists"
- "Modify `config.py` (if present)"
- "Create or update `types.ts`"

**Based on investigator report, ALWAYS write:**
- "Create `src/auth.ts`" (investigator confirmed doesn't exist)
- "Modify `src/index.ts:45-67`" (investigator confirmed exists, checked line numbers)
- "No changes needed to `config.py`" (investigator confirmed already correct)

**If codebase state differs from design assumptions:** Document the difference and adjust the implementation plan accordingly.

### 4. External Dependency Research

**When phases involve external libraries or dependencies, research them before writing tasks.**

Use a tiered approach—start with documentation, escalate to source code only when needed.

#### Tier 1: Internet Researcher (default)

Use `internet-researcher` for:
- Official documentation and API references
- Common usage patterns and examples
- Standard specifications (OAuth2, JWT, HTTP, etc.)
- Best practices and known gotchas

**This handles ~80% of external dependency questions.** Most integration work follows documented patterns.

#### Tier 2: Remote Code Researcher (escalation)

Use `remote-code-researcher` when:
- Documentation doesn't cover your edge case
- You need to understand internal implementation for extension/customization
- Docs describe *what* but you need to know *how*
- Behavior differs from docs and you need ground truth
- You're extending or hooking into library internals

#### Decision Framework

```
Phase involves external dependency?
├─ No → codebase-investigator only
└─ Yes → What do we need to know?
    ├─ API usage, standard patterns → internet-researcher
    ├─ Standard/spec implementation → internet-researcher
    ├─ Implementation internals, extension points → remote-code-researcher
    └─ Both local state + external info → combined-researcher
```

#### When to Dispatch

**Dispatch internet-researcher when phase mentions:**
- External packages/libraries to integrate
- Third-party APIs to call
- Standards to implement (OAuth, JWT, OpenAPI, etc.)

**Escalate to remote-code-researcher when:**
- Internet-researcher returns "docs don't cover this"
- Task requires extending library behavior
- Task requires matching internal patterns not in docs
- You need to understand error handling, edge cases, or internals

#### Reporting Findings

Include external research findings alongside codebase verification:

```markdown
**External dependency investigation findings:**
- ✓ Stripe SDK uses `stripe.customers.create()` with params: {email, name, metadata}
- ✓ OAuth2 refresh flow per RFC 6749 Section 6
- ✗ Design assumed sync API, but library is async-only
- + Error handling uses typed exception hierarchy (StripeError subclasses)
- 📖 Source: [Official docs | RFC spec | Source code @ commit]
```

**Standards vs Implementation:** Standards questions (e.g., "how does OAuth2 work") are internet-researcher territory. Implementation questions (e.g., "how does auth0-js store tokens") may require remote-code-researcher.

## Bite-Sized Task Granularity

**Each step is one action (2-5