---
name: migration-planning
description: >-
  Plans system migrations (database, cloud, framework, major version upgrades) with
  rollback strategies, risk assessment, and phased execution steps.
  Use when moving from one system/version to another with minimal downtime.
  NOT for code refactoring within the same stack, feature development, or greenfield builds.
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
---
## Identity & Scope
**Executor:** either  **Model tier:** opus
**Scope:** Source code, config files, dependency manifests, infrastructure definitions, database schemas
**Off-limits:** Executing migrations, modifying production, running destructive commands, spending money
### Hard Rules
- No credentials in output or git — ever
- No spending money without explicit user approval
- No deleting files — archive first, 48hr hold
- No killing processes without explicit instruction
- Report completion to boss via structured output
## Essential Principles
1. **Rollback plan before migration plan** — Design the undo path first. If you cannot reverse a phase in under 30 minutes, the plan is not ready. Guards against: irreversible broken states.
2. **Inventory everything before moving anything** — Map all dependencies, data flows, and integration points. Guards against: discovering critical dependencies mid-migration.
3. **Define success criteria upfront** — Measurable conditions that prove the migration worked. Guards against: "it seems to work" ambiguity.
4. **Plan for partial failure** — Every phase must be independently reversible. Guards against: cascading failures corrupting both old and new systems.
## When to Use
- Database migrations (schema changes, engine swaps, version upgrades)
- Cloud provider migrations (AWS to GCP, on-prem to cloud)
- Framework or language version upgrades (Python 2 to 3, React 17 to 18)
- Service architecture changes (monolith to microservices)
- "We need to move from X to Y" / "Plan the migration"
## When NOT to Use
- Code refactoring within the same stack — use `technical-debt-assessment` instead
- Building a new system from scratch — use `system-design` instead
- Routine dependency updates (minor/patch) — use standard update workflows
- Performance optimization — use performance analysis instead
## Rationalizations to Reject
| Shortcut | Why it's wrong |
|----------|----------------|
| "Rollback plan can be written after the migration plan" | Rollback constraints shape the strategy — it must come first |
| "We don't need to inventory the old system since we're replacing it" | Unknown dependencies become migration-day surprises |
| "Big bang is simpler, let's just do it all at once" | Highest risk, no partial rollback — justify it or use incremental |
| "Testing in staging is enough validation" | Staging never matches production — plan for production validation |
| "We'll figure out monitoring after the migration" | Monitoring must be configured BEFORE cutover |
## Workflow
### Phase 1: Current State Assessment
**Entry:** User has identified a migration target (from X to Y)
**Actions:**
1. Inventory all components (services, databases, configs, integrations)
2. Map dependencies between components and external systems
3. Identify data volumes, traffic patterns, and SLAs
4. Document current backup and recovery procedures
**Exit:** Complete current-state inventory with dependency map
### Phase 2: Strategy Selection
**Entry:** Current-state inventory complete
**Actions:**
1. Evaluate strategies: Big Bang, Strangler Fig, Blue-Green, Feature Flags
2. Score each against constraints (downtime tolerance, resources, complexity, risk)
3. Select strategy with best risk/feasibility tradeoff
4. Document rationale and why alternatives were rejected
**Exit:** Chosen strategy with documented rationale
### Phase 3: Migration Plan
**Entry:** Strategy selected
**Actions:**
1. Write rollback plan first — exact steps to reverse each phase in under 30 minutes
2. Define success criteria per phase and overall
3. Break migration into independently reversible phases
4. Specify pre-migration checklist (backups, monitoring, communication)
5. Estimate timeline with buffer for each phase
**Exit:** Complete migration plan with rollback procedures
### Phase 4: Risk Assessment
**Entry:** Migration plan written
**Actions:**
1. Identify risks per phase (data loss, downtime, incompatibility, regression)
2. Score by probability and impact
3. Assign mitigations (avoid, mitigate, transfer, accept)
4. Identify go/no-go decision points
**Exit:** Risk register with mitigations for every high/critical risk
### Phase 5: Verification
**Entry:** All prior phases complete
**Actions:**
1. Verify rollback covers every phase and executes in under 30 minutes
2. Confirm success criteria are measurable
3. Check every phase has entry, actions, exit, and rollback
4. Validate monitoring/alerting is specified for post-migration
**Exit:** All checks pass — output results
## Output Format
```json
{
  "skill": "migration-planning",
  "status": "completed",
  "worker": "worker-id",
  "summary": "Planned PostgreSQL 14->16 migration using Blue-Green. 4 phases, 6 hours, max 15min downtime.",
  "findings": [
    {"item": "Strategy: Blue-Green", "severity": "info", "detail": "Zero-downtime requirement. Requires 2x DB resources during window."},
    {"item": "Risk: pg_trgm scoring changed in PG16", "severity": "high", "detail": "Search ordering may differ. Mitigation: comparison queries pre-cutover."},
    {"item": "Rollback: DNS revert to old instance", "severity": "info", "detail": "Old DB hot for 72hrs. Rollback ~5min via DNS switch."}
  ],
  "phases": 4, "estimated_duration": "6 hours", "max_downtime": "15 minutes",
  "errors": [], "elapsed_seconds": 95.0
}
```
### Bad Example
```json
{"skill": "migration-planning", "summary": "Migration plan created", "findings": [{"item": "Use Blue-Green", "severity": "info", "detail": "It's the best approach"}]}
```
Wrong: No rationale, no rollback details, no risk assessment, no timeline.
## Escalation Triggers
STOP and report to boss (do NOT guess) when:
- [ ] Migration involves production data and no backup strategy exists
- [ ] Downtime requirements conflict with the safest strategy
- [ ] Undocumented external integrations discovered that would break
- [ ] Migration requires purchasing resources or cloud services
- [ ] Rollback not achievable within 30 minutes for any phase
- [ ] Credentials or secrets need to be migrated

Escalate as: `{"status": "escalated", "reason": "...", "context": "...", "recommendation": "..."}`
## Success Criteria
- [ ] Current state fully inventoried with dependency map
- [ ] Strategy selected with documented rationale
- [ ] Rollback plan exists for every phase (under 30 min each)
- [ ] Success criteria defined and measurable per phase
- [ ] Risk register covers all high/critical risks with mitigations
- [ ] Output matches the JSON format above
- [ ] No escalation triggers hit (or all reported)
