implementation-plan

Restate the goal in one sentence, pin observable acceptance criteria, inventory affected files with git grep or ripgrep, then order steps so each leaves the build green. Bind every criterion to an exact test command and define a rollback path for any irreversible step.

Isolate the migration on its own dedicated step, separate from code changes, and make it reversible with a down migration or backup. Use the expand/migrate/contract pattern: add the new column, backfill and dual-write, then drop the old column in a later release.

A spec defines what to build and why, including user problems and success metrics. An implementation plan defines how: the file-level changes, ordered steps, verification commands, risks, and rollback path an executor follows.

Skip planning for one-line fixes in leaf functions with full test coverage and no external callers. Also avoid planning when requirements are still undefined, since a plan built on a vague goal plans the wrong work.

Build thin vertical slices where each increment delivers working end-to-end functionality, passes tests, and is committed before the next slice. Tackle the riskiest piece first, and use feature flags to merge incomplete work without exposing it.

Common causes are guessed file inventories that miss callers, steps that temporarily break the build, test commands that do not exist in package.json, and migrations with no down path. Verify every command is real and every step is independently shippable.