/create-implementation-plan

name: create-implementation-plan
description: Turn a refined requirements document into a structured implementation PLAN.md a fresh session can execute. Planning only — decides the "how", not the "what". Invoke manually only.
license: MIT
metadata:
  version: "1.22"

Create Implementation Plan

**Planning only** — no code changes, no implementing. You produce one document: an implementation plan that is the contract for a later execution session.

This is the **"how", not the "what"**. The "what" was settled in an earlier refinement step and lives in the requirements document you're given; do not redefine scope. But you **must flag** any gap, ambiguity, or inconsistency you find in the requirements — surface it, never paper over it.

Golden rule

**Never guess — ask.** With one limit: anything resolvable by reading the codebase, resolve by reading the codebase; only questions the code cannot settle go to the user.

Steps

Your task is to **produce the implementation plan**. The steps below build toward it; grilling the user — interviewing relentlessly to resolve anything the code can't settle — is woven through the design, not a separate phase that runs before planning starts.

1. **Read the requirements document** the user references (e.g. a `*.REQUIREMENTS.md`). If the path is ambiguous, ask. Its Open questions are forks to grill in step 3, each with its tentative answer as the recommendation; none stays open in the plan. Its Overrides carry over into part 2's Overrides.

2. **Verify against the actual codebase.** Open the files the requirements cite and confirm the prior-art references still hold; note anything that has shifted since the requirements were written. The requirements may also carry verified codebase facts — use any that are there to save re-discovery work, aware the code may have moved meanwhile (a pinned commit makes the check cheap: `git diff <commit>..HEAD -- <cited paths>`). If the requirements gate implementation on missing data or upstream work, verify that gate independently — stale gating claims are a common failure mode and easily inflate into a plan's first step when the data is in fact already addressable. Check, read-only, which open PRs and recently active branches touch the files the plan will edit (those the requirements cite, and again any step 3 adds); each overlap goes in the How of the step editing that file, with how that step keeps the later rebase small.

3. **Work out the approach.** This is the core of the task: design the "how" — what existing code to reuse, what to introduce, where each change goes, and the order of operations that avoids broken intermediate states (data model before its consumers, code before its tests, a bug's regression test aside: see the Plan file's Steps). Track dependencies between steps. Working this out surfaces the **decision tree**: the forks where more than one reasonable approach exists. Typical forks to design through (and grill on when the code can't settle them): whether to refactor existing code to reuse it or build anew; which API or interface to call; which unit tests to add; code style, file names, and folder structure.

**Docs generally outrank prior art.** A mirrored analogue doesn't override a documented rule, and a rule's rationale doesn't license exceptions to it — existing code may predate the rule. When docs and prior art conflict and you're unsure how to resolve it, ask the user; a deviation the user approves is recorded in the plan's Overrides section, so the execution session knows it's deliberate.

**Prior art models shape, not content.** Its settings fit its own runtime, tooling and purpose and may predate the current ones, so before a step reuses a file, check each setting against the new component's target and prescribe only what fits, citing the file for shape; "copy X verbatim" is a decision settled line by line, never by the file's existence. A technical claim a step rests on ("X needs exactly Y") is verified against a doc, a compile or a test, never read off what the prior art happens to do. A command a step tells the session to run is such a claim. Run it first, as written, from the directory the step names, on today's code, when it is cheap and safe: it only reads or validates (a lint, a test, a build), writes nothing shared (a database, a service), and is small (one package or module, expected to finish in a minute or two; every package in a repo, or a large project as a whole, is too much). One that fails for a cause the planned changes would not fix (an unrelated module that fails to build, missing test data) is rescoped in that step's How with its reason, never left for the session to discover. One that changes state (a generator, a migration, a deploy), costs more than that, or runs on something an earlier step creates is never run while planning: check only that it resolves (the tool is installed, the flag exists).

**Deletions tend to cascade.** When a step deletes code, look for what that code was the last user of (a module, helper, template, constant, package) by searching for each one's other users, and consider naming it for deletion too, repeating for every piece newly orphaned; one the search cannot clear (an export, a name resolved at runtime) is a fork to grill. Each test deleted with its code gets a verdict by behaviour: the part that checks something the surviving code still does moves to a test the step names in its Where, and only the rest is deleted. A step that moves or renames code searches docs, agent instructions, CI workflows, build scripts and config for the old name in every form it is written (case and separator variants) and lists every hit in its Where.

**Walk every point a run can stop** when steps change live state in stages (a deploy, a migration, a swap): each step, an abort, a timeout, a