migration-planner

name	migration-planner
description	Plans safe framework, library, API, database, or architecture migrations with phased rollout, compatibility checks, and rollback strategy.

Migration Planner

Use this skill when a user wants to move from one version, framework, library, API, runtime, schema, or architecture pattern to another.

Inputs

• Current and target versions or architectures
• Affected services, packages, database objects, APIs, or user workflows
• Constraints such as downtime tolerance, compatibility requirements, release windows, and rollback needs

Steps

1. Inventory the affected surface area: imports, configuration, APIs, data schemas, tests, generated code, documentation, and deployment paths.
2. Identify breaking changes, compatibility gaps, deprecations, behavior changes, and transitive dependency impacts.
3. Split the migration into phases that preserve working software after each phase.
4. Define verification for each phase: unit tests, integration tests, smoke checks, data validation, metrics, and manual QA.
5. Plan rollout and rollback: feature flags, dual writes, compatibility shims, canaries, backups, and cutover criteria.
6. Call out high-risk unknowns and create small discovery tasks for them.
7. Produce an implementation order that minimizes blast radius.

Output

Return:

• Migration summary and scope
• Phased plan with tasks, owners or modules, and validation
• Breaking changes and compatibility strategy
• Rollout and rollback plan
• Open questions and risk register

Guidelines

• Prefer reversible phases over large rewrites.
• Keep user-facing behavior stable unless the migration explicitly changes it.
• Separate discovery tasks from implementation tasks.