| name | migration-planner |
| display_name | Migration Planner |
| description | Plans safe framework, library, API, database, or architecture migrations with phased rollout, compatibility checks, and rollback strategy. |
| category | code-quality |
| version | 1.0.0 |
| tags | ["migration","refactoring","planning","compatibility","rollout"] |
| providers | ["claude-code","codex","copilot","openclaw","hermes-agent"] |
| author | agent-skills contributors |
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
- Inventory the affected surface area: imports, configuration, APIs, data schemas, tests, generated code, documentation, and deployment paths.
- Identify breaking changes, compatibility gaps, deprecations, behavior changes, and transitive dependency impacts.
- Split the migration into phases that preserve working software after each phase.
- Define verification for each phase: unit tests, integration tests, smoke checks, data validation, metrics, and manual QA.
- Plan rollout and rollback: feature flags, dual writes, compatibility shims, canaries, backups, and cutover criteria.
- Call out high-risk unknowns and create small discovery tasks for them.
- 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.
