Migration Planning
Purpose
Plan a safe, incremental migration from a current state to a target state, keeping the system working between steps where possible and preserving a rollback path. Produces a migration work item in ../../work-items/migrations/.
When to Use
- Request classified as migration (framework/version/data/schema/infra).
- Not for in-place feature work or behavior-preserving cleanup.
Inputs
- Current state and target state (versions, schema, infra).
- Audit findings (
existing-project-audit, dependency-audit, environment-audit).
Discovery Questions
- What is the exact from → to, and why now?
- What breaks between them (breaking changes, data shape, contracts)?
- Can old and new coexist during transition (compatibility window)?
- What is the rollback plan, and are backups in place for data/schema?
- Is production involved (requires approval)?
Responsibilities
- Characterize the gap (from → to) and breaking changes.
- Plan incremental, reversible steps with a compatibility strategy.
- Define per-step verification and a rollback path.
- Define an explicit cutover with go/no-go criteria.
- For data/schema: require backups and a tested rollback.
- Flag production steps for approval (
../../mcp/PERMISSION_RULES.md).
Required Workflow
- Confirm the migration is justified — for a technology or version change, by a trigger in
../../system/TECHNOLOGY_GOVERNANCE_RULES.md §4, recorded in ../../templates/TECHNOLOGY_DECISION.md. Audit current + target state; list breaking changes from the official migration guide for the target version, and protect the behavior it could affect with regression scenarios.
- Design a compatibility strategy (dual-run/adapters where possible).
- Break into incremental, reversible steps.
- Define verification per step + rollback.
- Define cutover criteria.
- Record the migration work item; mark approval-required steps. On a tracked project, steps become
TECH- tasks and the cutover a DEPLOY- task, scheduled by project-management (../../system/PROJECT_MANAGEMENT_RULES.md).
Decision Rules
- Prefer incremental + reversible over big-bang cutover.
- Data/schema migrations require backups and a tested rollback before running.
- Keep the system functional between steps whenever feasible.
- Production migrations are outward-facing — explicit approval (
../../system/OPERATING_RULES.md).
Rules
- No irreversible data step without a verified backup/rollback.
- Verify at each step, not just at the end.
- Record the "why now" and the cutover criteria.
Anti-Patterns
- Big-bang production migration with no rollback.
- Skipping the compatibility window when one is feasible.
- Running data migrations without backups.
- Cutting over without go/no-go criteria.
Validation Checklist
Definition of Done
A recorded migration work item: characterized gap, compatibility strategy, incremental reversible steps with verification and rollback, backup plan for data/schema, and explicit cutover criteria — with production steps flagged for approval.
Related Skills
existing-project-audit, dependency-audit, environment-audit, task-planning, testing-strategy, security-review, release-planning, project-orchestrator, project-management.
Related Knowledge
../../knowledge/ (current architecture, data model).
Related References
../../references/<migration-topic>/ for framework upgrade guides if needed.
Context Loading Guidance
- Requires: current + target state, audit findings, breaking-change info.
- Does not require: unrelated modules, the full reference tree, unrelated skills.
- May load:
dependency-audit, environment-audit, release-planning for cutover.
- Stop when: steps, verification, rollback, and cutover are recorded.
Token Efficiency Guidance
Focus on the changed surface (deps, schema, config), not the whole app. Summarize breaking changes; link upgrade guides rather than pasting them.
1---2name: migration-planning3description: Use to plan a move from one state to another (framework/version/data/schema/infra) safely and incrementally, with a compatibility strategy, per-step verification, a rollback path, and an explicit cutover. Production migrations require approval.4metadata:5 source: https://skillmd.com/skills/ahtishamshahzad/migration-planning6---78# Migration Planning910## Purpose1112Plan a safe, incremental migration from a current state to a target state, keeping the system working between steps where possible and preserving a rollback path. Produces a migration work item in `../../work-items/migrations/`.1314## When to Use1516- Request classified as **migration** (framework/version/data/schema/infra).17- **Not** for in-place feature work or behavior-preserving cleanup.1819## Inputs2021- Current state and target state (versions, schema, infra).22- Audit findings (`existing-project-audit`, `dependency-audit`, `environment-audit`).2324## Discovery Questions2526- What is the exact from → to, and why now?27- What breaks between them (breaking changes, data shape, contracts)?28- Can old and new coexist during transition (compatibility window)?29- What is the rollback plan, and are backups in place for data/schema?30- Is production involved (requires approval)?3132## Responsibilities3334- Characterize the **gap** (from → to) and breaking changes.35- Plan **incremental, reversible steps** with a compatibility strategy.36- Define **per-step verification** and a **rollback path**.37- Define an explicit **cutover** with go/no-go criteria.38- For data/schema: require **backups** and a tested rollback.39- Flag production steps for approval (`../../mcp/PERMISSION_RULES.md`).4041## Required Workflow42431. Confirm the migration is justified — for a technology or version change, by a trigger in `../../system/TECHNOLOGY_GOVERNANCE_RULES.md` §4, recorded in `../../templates/TECHNOLOGY_DECISION.md`. Audit current + target state; list breaking changes from the **official migration guide for the target version**, and protect the behavior it could affect with regression scenarios.442. Design a compatibility strategy (dual-run/adapters where possible).453. Break into incremental, reversible steps.464. Define verification per step + rollback.475. Define cutover criteria.486. Record the migration work item; mark approval-required steps. On a tracked project, steps become `TECH-` tasks and the cutover a `DEPLOY-` task, scheduled by `project-management` (`../../system/PROJECT_MANAGEMENT_RULES.md`).4950## Decision Rules5152- Prefer incremental + reversible over big-bang cutover.53- Data/schema migrations require backups and a tested rollback before running.54- Keep the system functional between steps whenever feasible.55- Production migrations are outward-facing — explicit approval (`../../system/OPERATING_RULES.md`).5657## Rules5859- No irreversible data step without a verified backup/rollback.60- Verify at each step, not just at the end.61- Record the "why now" and the cutover criteria.6263## Anti-Patterns6465- Big-bang production migration with no rollback.66- Skipping the compatibility window when one is feasible.67- Running data migrations without backups.68- Cutting over without go/no-go criteria.6970## Validation Checklist7172- [ ] From → to and breaking changes characterized.73- [ ] Compatibility strategy defined.74- [ ] Incremental reversible steps.75- [ ] Per-step verification + rollback.76- [ ] Backups planned for data/schema.77- [ ] Cutover criteria defined.78- [ ] Production steps flagged for approval.7980## Definition of Done8182A recorded migration work item: characterized gap, compatibility strategy, incremental reversible steps with verification and rollback, backup plan for data/schema, and explicit cutover criteria — with production steps flagged for approval.8384## Related Skills8586`existing-project-audit`, `dependency-audit`, `environment-audit`, `task-planning`, `testing-strategy`, `security-review`, `release-planning`, `project-orchestrator`, `project-management`.8788## Related Knowledge8990`../../knowledge/` (current architecture, data model).9192## Related References9394`../../references/<migration-topic>/` for framework upgrade guides if needed.9596## Context Loading Guidance9798- **Requires:** current + target state, audit findings, breaking-change info.99- **Does not require:** unrelated modules, the full reference tree, unrelated skills.100- **May load:** `dependency-audit`, `environment-audit`, `release-planning` for cutover.101- **Stop when:** steps, verification, rollback, and cutover are recorded.102103## Token Efficiency Guidance104105Focus on the changed surface (deps, schema, config), not the whole app. Summarize breaking changes; link upgrade guides rather than pasting them.