plan-migration
/plan-migration
Plan a framework, runtime, dependency or schema upgrade that touches many files, without a big-bang rewrite. Use when asked to upgrade to a new major version, replace a library, split a monolith, move a package between repos, or when a previous migration stalled half-finished and left two ways of doing the same thing.
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 30.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Plan a framework, runtime, dependency or schema upgrade that touches many files, without a big-bang rewrite. Use when asked to upgrade to a new major version, replace a library, split a monolith, move a package between repos, or when a previous migration stalled half-finished and left two ways of doing the same thing.
Original author description
Plan a framework, runtime, dependency or schema upgrade that touches many files, without a big-bang rewrite. Use when asked to upgrade to a new major version, replace a library, split a monolith, move a package between repos, or when a previous migration stalled half-finished and left two ways of doing the same thing.
How it works
- When to use
- Ground rules
- Procedure
- Anti-patterns
- Definition of done
- Report format
SKILL.md preview
--- name: plan-migration description: Plan a framework, runtime, dependency or schema upgrade that touches many files, without a big-bang rewrite. Use when asked to upgrade to a new major version, replace a library, split a monolith, move a package between repos, or when a previous migration stalled half-finished and left two ways of doing the same thing. license: MIT --- # Plan a migration that can be abandoned halfway The danger in a migration is not the change; it is the state you are in when it stops. A plan is only as good as the point it can be safely paused at, reverted from, or finished by someone who is not you. ## When to use - A major version bump, a runtime upgrade, a library replacement, or a monolith split. - A previous migration left the codebase with two conventions and nobody remembers which is current. - Someone proposes "we'll just rewrite it" for anything larger than a day of work. Not for: a mechanical rename in three files, or a single dependency patch. ## Ground rules 1. **Inventory before you plan.** You cannot schedule work whose size you have not counted, and you cannot claim "it is nearly done" without a denominator. 2. **Every step leaves the project working and shippable.** If a step cannot be shipped, it is not a step, it is a branch. 3. **Codemods over hand-editing**, and a reviewable diff over a heroic one. 4. **Two ways of doing something is a temporary state with an end date**, written down, or it becomes permanent — the fixture that never gets deleted. 5. **The compatibility matrix is the plan.** Old and new versions, and which combinations are legal, decide the ordering more than anything else. 6. **Know the abort point.** What exactly would make you stop, and what does the tree look like when you do. ## Procedure 1. **Inventory the surface.** Count the call sites, the files, the packages and the APIs in play, with a command, not an impression: ```bash rg -l 'oldApiName' | wc -l # files to touch rg -c 'oldApiName' | sort -t: -k2 -nr | head # where the weight is npm ls old-package # who depends on it, directly and transitively ``` 2. **Read the upgrade guide and write the breaking changes as a checklist**, in your own words, each with a detection command. Anything you cannot detect, you cannot verify. 3. **Build the compatibility matrix**: which versions of the toolchain, runtime and dependencies may coexist. This usually dictates a strict ordering (runtime first, or the framework first) that saves days of dead ends. 4. **Choose the strategy and say why**: | Strategy | Use when | Cost | | --- | --- | --- | | Incremental with a compatibility layer | Many call sites, live product | Extra abstraction to remove later | | Strangler (new path alongside old, switch by flag or route) | Behaviour change, need gradual rollout | Two paths running at once; needs an end date | | Codemod then manual review | Purely mechanical API rename | Nothing, if the codemod is verifiable | | Big-bang rewrite | Small surface, no users mid-flight, strong test suite | All the risk lands at once | 5. **Order the steps by "what unblocks the most" and "what is reversible"**. Put the reversible, high-leverage work first; leave irreversible data migrations for last, behind a backup. 6. **Add the verification before the change.** A test, a type check, a golden file or a snapshot that fails for the old behaviour makes the migration mechanical. If the suite is too thin to catch a regression, that is the first task, not an excuse. 7. **Run the steps as separate pull requests**, each with: what changed, what proves it, what is still on the old path, and the remaining count (`63 / 214 call sites`). Visible progress is what keeps a migration from stalling. 8. **Remove the scaffolding deliberately.** When the last old path is gone: delete the compatibility layer, the flag, the deprecated module and every leftover note, in one final commit. ## Anti-patterns | Tempting move | Why it is wrong | | --- | --- | | A branch that lives for weeks | It merges as a conflict generator, and nobody can review it | | "We'll fix the warnings later" | Later is a second migration, on top of this one | | Keeping the old and new API both "for safety" | That is not safety, that is two products | | Migrating and refactoring in the same commit | When it breaks, you cannot tell which change did it | | Rewriting tests to match new behaviour mid-migration | You have deleted the evidence that the behaviour was meant to stay | | No inventory, so "80 % done" for a month | Without a denominator, progress is unmeasurable and morale collapses | ## Definition of done - [ ] Inventory with a command and a number; the number is at zero. - [ ] Compatibility constraints were written down and respected. - [ ] Every step shipped independently and left the project working. - [ ] The old path, flag and compatibility layer are **deleted**, not deprecated. - [ ] The test suite proves the behaviour survived; any behaviour that changed on purpose is listed. - [ ] Documentation and examples updated — a migration that leaves the docs on the old API is half done. - [ ] The rollback story is gone on purpose: you can roll back the deployment, not the change. ## Report format ``` Goal: <old → new, and why now> Surface: <count> call sites in <count> files, <count> packages Strategy: <incremental | strangler | codemod | big-bang>, because <one sentence> Order: <the steps, in order, with the reason for the order> Risk: <the irreversible part, and its backup> Progress: <n / total>, and what is left Abort point: <what would stop this, and the tree state if it does> ``` A worked template, including the compatibility matrix and the per-PR description, is in [references/migration-template.md](references/migration-template.md).
Files in this package (2)
- SKILL.md 6 KB
- references/migration-template.md 4 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · AmirAzy/HoNspot | 100 | MIT |
| krzysztofsurdy/code-virtuoso | 90 | MIT |
Database snapshot: 13.11.2026 · package version 29f58473a0d2 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100dependency-migration
Plan and carry out a dependency or framework upgrade or replacement in small, verifiable steps. Use when the user asks to upgrade a major version, replace one library with another, or migrate off a deprecated package or API. - 95migrate
Autonomous migration planning and execution. Takes a migration target (framework upgrade, API version bump, dependency major version, deprecation removal) and produces a phased migration plan with compatibility verification, then optionally executes via build's refactor mode.… - 95migrate
[UDS] Guide systematic code migration, framework upgrades, and technology modernization. Use when: planning a framework or major-version upgrade, assessing migration risk, capturing contract-test fixtures before an API migration. Not for: in-place improvement that keeps the same… - 100migration
Use when upgrading a framework version, migrating APIs, bumping major dependencies, or any task where "before" and "after" states must be compared. Auto-invoke when user mentions migration, upgrade, breaking changes, or version bumps. - 100cursor-upgrade-migration
Execute upgrade Cursor versions and migrate settings. Triggers on "upgrade cursor", "update cursor", "cursor migration", "cursor new version", "cursor changelog". Use when working with cursor upgrade migration functionality. Trigger with phrases like "cursor upgrade migration",… - 100framework-upgrade
Generic framework upgrade orchestrator (audit|plan|migrate|validate) with pluggable packs. Use when upgrading a framework version or invoking /framework-upgrade.