# Migration Plan: [system / data]

> Moving [data / traffic / users] from [old] to [new] without losing
> either. The rollback plan is a section, not a hope.

| Field | Value |
|-------|-------|
| Migration | [name] |
| Owner | @name |
| Window | YYYY-MM-DD to YYYY-MM-DD |
| Approvers | @name, @name |
| Status | Planning / In flight / Done / Rolled back |

## Current -> target state

| Aspect | Current | Target |
|--------|---------|--------|
| System | [old] | [new] |
| Data volume | [N records / size] | [same / transformed] |
| Consumers | [list] | [list] |

## Strategy

Pattern chosen: big-bang / phased / strangler / dual-write.

```mermaid
flowchart LR
    A[Old system] -->|dual write| B[New system]
    A -->|backfill| B
    B -->|verified| C[Cutover]
```

Rationale: [why this pattern over the alternatives]

## Steps

| # | Step | Command / action | Verify | Owner |
|---|------|------------------|--------|-------|
| 1 | Backfill | `...` | Row counts match | @name |
| 2 | Shadow read | `...` | Diff rate < N% | @name |
| 3 | Cutover | `...` | Traffic 100% on new | @name |
| 4 | Decommission | `...` | Old system off | @name |

## Rollback

Trigger conditions – agreed in advance, not negotiated at cutover:

- Error rate > N% for N minutes
- Data reconciliation diff > N records
- SLO burn rate > Nx

Rollback procedure: [reverse steps, restore point, flag/DNS to flip].
Rollback decision owner: @name.

## Data integrity

- Reconciliation method: [checksums / row counts / sampling]
- Sample verification: [N records, which fields]
- Write-drift policy during migration: [queue / dual-write / freeze]

## Risks

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| | | | |

## Communication

| Audience | When | Channel | Owner |
|----------|------|---------|-------|
| Team | T-7 days | [channel] | @name |
| Users | T-0 | [status page] | @name |

## Post-migration checklist

- [ ] Monitoring confirms new system healthy for N days
- [ ] Old system set read-only, then decommissioned
- [ ] Docs and runbooks updated
- [ ] Retrospective scheduled