# Implementation Planning

Turns a specification into the ordered set of changes a developer executes — every step leaving the tree building and the system working.

## Deliverable

One Markdown document, `implementation-plan.md`, in the structure set out under **Output** below. It takes an agreed specification and feeds **Code Review** once the steps start landing.

## Required inputs

- **The specification** — what must be true when the work is done, in whatever form it was agreed: a scope document, a ticket, a written brief.
- **Access to the codebase the change lands in** — enough to open the files, read the build configuration and run the test suite.
- **The branch or baseline the work starts from**, so the steps are ordered against a known tree.

If any of the three is absent, stop and report which one. A plan written without the codebase names files that may not exist, and a plan written without a baseline cannot be ordered.

## Optional inputs

- The test suite and how it is run, including which parts are slow or unreliable
- Coding conventions, review requirements and the merge process
- Interfaces owned by other teams that this work must call or satisfy
- Deployment constraints: feature switches, migrations, release windows
- Earlier attempts at the same change, and where they stopped
- The people who will execute the steps, at least by role

Each absent optional input is recorded under **Open items**, and the steps it would have constrained are marked `unverified`. None of them is assumed.

## Execution

**1 — Read the specification against the code.** For each requirement, find the module, file or function it lands in and record the path. A requirement whose landing point cannot be found is listed as `needs investigation` with the search that failed — never assigned to a file that merely sounds right.

**2 — List the interfaces first.** Every function signature, data shape, schema change or contract that dependent work needs before it can start. These become the earliest steps, because work blocked on an interface that does not exist yet is work that stalls.

**3 — Order the changes so the tree builds at every point.** Follow the direction of the dependencies: a caller cannot land before the thing it calls compiles. Where two changes depend on each other, split one into an interface step and an implementation step, and say which.

**4 — Size each step to one commit.** A step is one reviewable unit with a single stated purpose. Anything that needs the word `and` in its purpose is two steps. State for each what it changes and what it deliberately leaves alone.

**5 — Attach the tests to the steps.** For each step: the tests written with it, what they assert, and the command that runs them. A step with no test states why one is not possible and what is checked instead.

**6 — Check the whole-system state after every step.** For each step, what must still work when it lands: the build, the test suite, the running system. A step that leaves the system broken until the next one lands is merged with that step or rewritten.

**7 — Record what the plan does not cover.** Work that needs investigation, decisions not yet made, and the steps whose ordering depends on an answer nobody has given yet.

## Output

`implementation-plan.md`, in this order:

- **1. Input and baseline** — which specification, which branch or commit, and when
- **2. Landing points** — one line per requirement: the requirement, the file or module, and how it was located
- **3. Interfaces** — the contracts that must exist first, each with the steps that depend on it
- **4. Steps** — ordered; per step: purpose, files touched, what it leaves alone, and the state of the system after it
- **5. Tests** — per step: the tests added, what they assert, the command that runs them
- **6. Checkpoints** — what must pass after each step, and what to do when it does not
- **7. Needs investigation** — requirements with no located landing point, each with the question and who can answer it
- **8. Open items** — decisions, access and information the plan is waiting on

## Validation

The plan is ready when all of these hold:

- Every requirement in the specification appears in section 2 or in section 7
- Every step names the files it touches, and every named file exists on the stated baseline
- No step depends on a later step
- Every step states the system state it leaves behind, and none of them is `broken`
- Every step either carries a test or states why it cannot
- No file path appears that was not found in the codebase

Fail the run if a step leaves the build unable to complete, or if a requirement was assigned to a file that could not be opened.

## Failure handling

- **No specification** — stop. Report that there is nothing to plan against, and that a plan derived from the code would restate what exists rather than what is wanted.
- **No access to the codebase** — produce sections 1, 3 and 7 only, mark every landing point `unverified`, and state that the ordering cannot be trusted until the files are read.
- **The specification contradicts the code** — record both, name the file and the requirement, and raise it in section 8 as blocking. Do not resolve it by choosing the one that is easier to build.
- **A requirement with no landing point** — list it in section 7 with the search that failed. Never invent a file for it.
- **Partial access** — plan the parts that were read, mark the rest `INCOMPLETE — pending access to <area>`, and deliver. The plan's reach is stated, not implied.