ed3dai/ed3d-plugins-testing/writing-implementation-plans

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 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:

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

For functionality tasks:

• "Write the failing test" - step
• "Run it to make sure it fails" - step
• "Implement the minimal code to make the test pass" - step
• "Run the tests and make sure they pass" - step
• "Commit" - step

For infrastructure tasks:

• "Create the config file" - step
• "Verify it works (install, build, run)" - step
• "Commit" - step

Task dependencies MUST be explicit and sequential:

• Task N requires helper function? Task N-1 creates it.
• Task N requires bootstrap credentials? Prior task provisions them.
• Never write code that assumes "this will exist somehow."

Task Types: Infrastructure vs Functionality

Match task structure to what the design phase specifies.

The design plan distinguishes between infrastructure phases (verified operationally) and functionality phases (verified by tests). Your implementation tasks must honor this distinction.

Infrastructure tasks (project setup, config files, dependencies):

• Don't force TDD on scaffolding
• Verification = operational success
• "npm install succeeds" is valid verification
• Verifies: None — explicitly state this, don't invent ACs for setup phases

Functionality tasks (code that does something):

• Tests are deliverables alongside code
• Each task lists which ACs it verifies (e.g., "Verifies: AC1.1, AC1.3")
• Tests must verify those specific AC cases, not just "test the code"
• Phase ends with passing tests for all ACs listed in the phase's AC Coverage

Test behavior, not implementation.

• Test that your function produces the right output, not that it called dependencies a certain way
• If you refactored internals but behavior stayed the same, would the test still pass? If no, you're testing implementation details.
• The AC is the spec: "Invalid password returns 401" means test the response, not verify that bcrypt.compare() was called

What doesn't need tests:

• Types (TypeScript compiler verifies these)
• Dependencies that have their own tests (don't re-test them through your code)
• How you call things (test the result, not the wiring)
• Infrastructure/setup (verify operationally)

Subcomponent task grouping. Design plans structure phases as subcomponents: types → implementation → tests. When writing tasks for a subcomponent, wrap them in subcomponent markers (see "Task and Subcomponent Markers" section):

<!-- START_SUBCOMPONENT_A (tasks 1-3) -->
<!-- START_TASK_1 -->
### Task 1: TokenPayload type and TokenConfig
...
<!-- END_TASK_1 -->
 
<!-- START_TASK_2 -->
### Task 2: TokenService implementation
...
<!-- END_TASK_2 -->
 
<!-- START_TASK_3 -->
### Task 3: TokenService tests
...
<!-- END_TASK_3 -->
<!-- END_SUBCOMPONENT_A -->

The execution agent uses these markers to identify related tasks. The tests task proves the subcomponent works.

Read the design plan's "Done when" section. If it says "build succeeds," don't invent unit tests. If it says "tests pass for X," ensure tasks produce those tests.

Plan Document Header

Every plan phase document MUST start with this header:

# [Feature Name] Implementation Plan
 
**Goal:** [One sentence describing what this builds]
 
**Architecture:** [2-3 sentences about approach]
 
**Tech Stack:** [Key technologies/libraries]