Skip to content
Skills Library
Programming · Planning

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.

Repository
HoNspot ↗
Licence
MIT
Last repository change
30.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 30.10.2026, without references to retired models or APIs.

Licence

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

  1. When to use
  2. Ground rules
  3. Procedure
  4. Anti-patterns
  5. Definition of done
  6. Report format
Original SKILL.md headings · 105 lines, 962 words
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

RepositoryScoreLicence
This page · AmirAzy/HoNspot100MIT
krzysztofsurdy/code-virtuoso90MIT

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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.