code_migration_runbook v1.0.0

name: "code_migration_runbook" description: "Plan and execute a code or system migration safely: pick the migration pattern, verify with parallel runs, and run the cutover with rollback checkpoints. Use when moving a legacy system, monolith, database, or dependency to a new implementation."

Code Migration Runbook

Purpose

Turn "we need to move off X" into a written, verifiable migration plan an agent can execute step by step, with the pattern chosen, the verification defined, and the rollback rehearsed before cutover day.

Workflow

1. Inventory. List every surface the old system touches: callers, data stores, background jobs, configs, downstream consumers. The count changes the strategy. Never skip this.
2. Choose the pattern (references/migration-patterns.md). Default to the strangler fig for legacy systems, expand-contract for schema or API changes, branch by abstraction for internal component swaps. Rule out the big-bang rewrite and say why in one line.
3. Write the runbook from assets/migration-runbook-template.md. Fill every section: inventory, pattern, verification plan, cutover sequence, rollback plan, point of no return, comms plan, cleanup date.
4. Build verification before cutover. Shadow or parallel-run the new path on real traffic, compare outputs, reconcile data with counts, checksums, and field-by-field samples. Cut over when verification passes, not when the clock says so.
5. Rehearse the rollback (references/rollback-and-cutover.md). Run the exact rollback procedure on a copy, with the on-call person driving. An untested rollback is a hypothesis.
6. Run the preflight check. python3 bin/migration-preflight.py runbook.md reports missing or empty sections. Fix every gap it flags.
7. Cut over in stages (shadow, then small traffic percentages, then full), watch the defined signals, execute the comms plan, then contract: delete the old code, the flag, the dual write, and the compatibility layer on the scheduled cleanup date.

Output Contract

• A completed migration runbook document with every template section filled (nothing left "TBD")
• A preflight report with zero blocking gaps
• Evidence of verification: comparison logs or reconciliation counts from the parallel run
• A dated cleanup commitment for removing the old path

Operating Rules

1. Never mix a migration with a feature change in the same release.
2. Never declare a migration finished while the old path still receives traffic or data.
3. Never leave a dual write, dual read, or feature flag in place without a removal date.
4. Never rely on a rollback that has not been rehearsed.
5. Never migrate data without a verification step and a written reverse path.
6. Cutover happens when verification passes, not when the schedule says so.
7. Delete the old path on the cleanup date. A migration left at ninety percent costs more than either end state.