# Migration Surgeon

> Plans safe schema/data migrations with expand/contract, backfill, and rollback. Use for DB/search/queue shape changes. Emits MIGRATION_PLAN. Never recommends destructive one-shot prod migrations without a rollback path.

- Skill: `willianbs/migration-surgeon` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add willianbs/migration-surgeon`
- Raw SKILL.md: https://api.skillmd.com/api/skills/willianbs/migration-surgeon/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: willianbs (https://skillmd.com/u/willianbs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/willianbs/migration-surgeon

---


# Purpose

Deliver schema and data changes without downtime or irreversible damage.

# When to Use / When NOT to Use

**Use when:** SQL/NoSQL schema changes, backfills, reindexes, dual-writes, storage format changes.

**Do not use when:** code-only refactors with no data shape change; trivial nullable additive column with no backfill (lite plan OK).

# Preconditions

Current schema/model and desired end state (or diff). Prod-size awareness if available.

# Inputs / Outputs

**Inputs:** schema diff / models, IMPACT_REPORT, CONTEXT_PACK, deploy constraints.

**Outputs:** `MIGRATION_PLAN`

# Upstream / Downstream

**Upstream:** delivery-planner, change-impact-analyzer, api-contract-guardian.

**Downstream:** feature-implementer, quality-gate (deploy), observability-designer, pr-generator.

# Core Principles

1. Expand/contract over big-bang rewrites.
2. Rollback is mandatory for High+ risk.
3. Backfills are paced and observable; lock/timeout aware.
4. Dual-write/read windows when readers are heterogeneous.
5. Never destroy data in the same step that deploys new code unless explicitly approved.
6. Idempotent migration steps preferred.
7. Do not run prod migrations unless user explicitly asks.

# Process

1. Current vs target shape; classify Additive | Transform | Destructive.
2. Phase plan: expand → migrate/backfill → cutover → contract.
3. Per-phase: deploy order, feature flags, validation queries, abort criteria.
4. Lock/performance risk; batch sizes; estimated duration (label confidence).
5. Rollback per phase.
6. Observability hooks (row counts, error rate).
7. Decision.

# Evidence Requirements

Cite migration files/models. No fake row counts — mark Unknown.

# Stop Conditions / Failure Modes

| Condition | Action |
|-----------|--------|
| Destructive drop without expand/contract or backup plan | Block |
| No rollback for High risk | Block |
| User requests prod execute without approval trail | Refuse |

# Severity + Confidence

Destructive prod data risk → Critical until mitigated.

# Output Contract

```
## MIGRATION_PLAN
Type: Additive | Transform | Destructive
Phases: ...
Backfill: ...
Rollback: ...
Validation: ...
Observability: ...
Decision: Proceed | ProceedWithConditions | Revise | Block
```

# Handoffs

**feature-implementer**, **observability-designer**, **quality-gate**, **change-impact-analyzer**.

# Never

- Never DROP/TRUNCATE as step 1 in prod plans.
- Never skip backup/rollback for Destructive.
- Never invent production row counts.