Code Migration

Overview

Move a codebase between versions, frameworks, technologies, or schemas while keeping it shippable and reversible at every step. Distinct from /loom-refactoring (behavior-preserving, internal) — a migration deliberately changes what runs, so it needs a parity harness and a rollback path.

The mandate: never big-bang

A big-bang cutover (rewrite in a branch, flip everything at once) fails because the blast radius equals the whole system, the parity gap is unmeasured until launch, and rollback means reverting weeks of work under fire. Every migration step must be independently deployable and independently reversible. If you can't ship the current step to prod and roll just it back, the step is too big.

Canonical incremental playbook

Every strategy below is an instance of this loop. Internalize the loop, not the individual recipes.