migration-plan

migration-plan

Plans the road from current state to target state so that at every moment the system is in a stable, reversible position — until the one explicitly named point of no return. The default shape is the parallel-change pattern: expand (add the new path alongside the old), migrate (move traffic/data with verification), contract (remove the old path — actually scheduled, not "later").

How to respond

1. Pin both ends. Current state and target state, stated concretely enough that "done" is checkable ("all reads served by the v2 endpoint and v1 returns 410", not "migrated to v2"). Ask at most 2 questions; spend them on the constraints that shape the plan — downtime tolerance and data volume. Everything else gets [assumption].

2. Cut phases by the one-change rule. Each phase changes one thing: schema or code path or traffic share — never two in the same step, because a failed phase must implicate exactly one change. ✅ "Phase 2: deploy dual-write code (schema already expanded in phase 1)" — ❌ "Phase 2: add the new column and start writing to it".

3. Give every phase the four mandatory fields (skeleton in templates/migration-plan.md):

   • Action — what changes
   • Gate — observable criteria to pass before the next phase (error rates, data parity, shadow-diff results), plus bake time; a zero-bake gate is a gate in name only
   • Rollback — the tested way back, ✅ "flip flag orders_v2_read off; old path still receives dual writes, no data loss" — ❌ "redeploy previous version" when data has already moved
   • Blast radius — who/what is affected if this phase fails If a phase has no real rollback, it is the point of no return: name it in bold, schedule it as late as possible, and list what must be verified immediately before crossing it. A plan may have one; a plan with three has its phases cut wrong.

4. Specify the backfill like an engineer will run it at 2am. Idempotent (safe to re-run), resumable (checkpointed, not restart-from-zero), rate-limited (with the limit and the metric that triggers slowdown), and verified by parity checks at three depths: row/object counts, checksums or aggregates per partition, and a sampled deep-compare. Dual-write without a reconciliation job is drift with a delay timer — if the plan dual-writes, it names the reconciler and its alert.