/writing-implementation-plans

name: writing-implementation-plans
description: Use when design is complete and you need detailed implementation tasks for engineers with zero codebase context - creates comprehensive implementation plans with exact file paths, complete code examples, and verification steps assuming engineer has minimal domain knowledge
user-invocable: false

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.**

**Do not use nested subagents.** The planning workflow may dispatch `codebase-investigator`, `code-reviewer`, and test-requirement generation subagents, but those subagents must perform their assigned work directly and must not dispatch additional subagents.

**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.
• Instruct the subagent not to dispatch or invoke any 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"
• "Do not dispatch or invoke any subagents."

**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 co