Migration Plan Drafter

---
name: migration-plan-drafter
description: Use when drafting a phased migration plan — library, framework, infra, or DB migration. Triggers on "migration plan", "upgrade plan", "cutover plan", "phased rollout".
---

# Migration Plan Drafter

Big-bang migrations fail. Every successful migration looks like a series of small, reversible steps with a parallel-run period and an honest rollback. Plan for partial failure, not the happy path.

## Required inputs

1. **Source state** — current versions, current architecture
2. **Target state** — exactly what you're moving TO
3. **Why now** — the forcing function (EOL, performance, cost, compliance)
4. **Blast radius** — services / users / data affected
5. **Acceptable downtime / regression budget** — be explicit
6. **Team capacity** — solo project, dedicated team, part-time?

If the user can't answer "how do we know it worked?" or "how do we revert?", that's the first thing to define.

## Plan structure

```
# Migration: [source] → [target]

## Goal
1-2 sentences. The user/business outcome, not just the technical change.

## Non-goals
What this migration is explicitly NOT doing. Prevents scope creep.

## Success criteria
- Concrete, measurable. "All services on Node 22, no >5% perf regression."
- How you'll measure them.

## Risk register
- Top 5 risks ranked by impact × likelihood
- For each: mitigation + early-warning signal

## Phases

### Phase 0: Prep (no production change)
- Inventory: every place using the old thing
- Test fixtures, CI updates, tooling
- Document the new thing for the team
- Exit criteria: [specific]

### Phase 1: Parallel implementation (no traffic)
- New code path written but not used
- Feature-flagged off
- Internal testing only
- Exit criteria: [specific]

### Phase 2: Gradual cutover
- 1% → 10% → 50% → 100% (or staged by service / region / customer tier)
- Cutover gates: at each stage, what metric must hold?
- Rollback trigger: what threshold reverses the percentage?
- Exit criteria: 100% on new path, X days clean

### Phase 3: Cleanup
- Delete old code path (NOT before Phase 2 has held for X weeks)
- Update docs, runbooks, ADRs
- Decommission infrastructure
- Exit criteria: old code gone, no remaining references
```

## Rollback plan (mandatory)

For EVERY phase:
- **What action triggers a rollback?** (specific metric / threshold / time)
- **What command / steps reverse it?** (one-line commands when possible)
- **How long to revert?** (minutes? if hours, that's a problem)
- **What state is unrecoverable?** Be honest — sometimes data is lost forever past phase X. Call this out so the team knows the point of no return.

If rollback time is >15 min, the migration is too aggressive. Slow down.

## Dual-run / shadow period

For data and traffic migrations, plan to run BOTH systems in parallel:
- New system reads same data, writes shadowed
- Compare results offline
- Don't cut over until shadow has matched for X days
- This is non-negotiable for anything stateful

## Communication plan

- Who's notified at each phase (eng, support, customers)
- Status updates cadence
- Where status lives (dashboard, channel)

## Anti-patterns

- "Migrate everything in one weekend" — never works
- No rollback because "it'll be fine" — it won't
- Cleanup phase that never happens; old code lives forever
- One person migrating 80 services alone — burnout + bus factor 1
- Skipping the inventory and discovering on Day 4 that 12 obscure services use the old thing

## Output

Markdown plan. Include a 1-page TL;DR at the top: phases, calendar dates, rollback summary. Engineers won't read 5 pages until it's time to execute their phase.