---
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.