Imported from 0xDarkMatter/claude-mods (skills/migrate-ops/SKILL.md). Install upstream with npx skills add 0xDarkMatter/claude-mods --skill migrate-ops. Copyright stays with the author (MIT).

Migrate Operations

Comprehensive migration skill covering framework upgrades, language version bumps, dependency auditing, breaking change detection, codemods, and rollback strategies.

Ecosystem facts verified as of 2026-07-05.

Migration Strategy Decision Tree

What kind of migration are you performing?
│
├─ Small library update (patch/minor version)
│  └─ In-place upgrade
│     Update dependency, run tests, deploy
│
├─ Major framework version (React 18→19, Vue 2→3, Laravel 12→13)
│  │
│  ├─ Codebase < 50k LOC, good test coverage (>70%)
│  │  └─ Big Bang Migration
│  │     Upgrade everything at once in a feature branch
│  │     Pros: clean cutover, no dual-version complexity
│  │     Cons: high risk, long branch life, merge conflicts
│  │
│  ├─ Codebase > 50k LOC, partial test coverage
│  │  └─ Incremental Migration
│  │     Upgrade module by module, use compatibility layers
│  │     Pros: lower risk per step, continuous delivery
│  │     Cons: dual-version code, longer total duration
│  │
│  ├─ Monolith → microservice or complete architecture shift
│  │  └─ Strangler Fig Pattern
│  │     Route new features to new system, migrate old features gradually
│  │     Pros: zero-downtime, reversible, production-validated
│  │     Cons: routing complexity, data sync challenges
│  │
│  └─ High-risk data pipeline or financial system
│     └─ Parallel Run
│        Run old and new systems simultaneously, compare outputs
│        Pros: highest confidence, catch subtle differences
│        Cons: double infrastructure cost, comparison logic
│
└─ Language version upgrade (Python 3.12→3.14, Node 22→26)
   └─ In-place upgrade with CI matrix
      Test against both old and new versions in CI
      Drop old version support once all tests pass

Framework Upgrade Decision Tree

Which framework are you upgrading?
│
├─ React 18 → 19
│  ├─ Check: Remove forwardRef wrappers (ref is now a regular prop)
│  ├─ Check: Replace <Context.Provider> with <Context>
│  ├─ Check: Adopt useActionState / useFormStatus for forms
│  ├─ Check: Replace manual memoization if using React Compiler
│  ├─ Codemod: npx codemod@latest react/19/migration-recipe
│  └─ Load: ./references/framework-upgrades.md
│
├─ Next.js Pages Router → App Router
│  ├─ Check: Move pages/ to app/ with new file conventions
│  ├─ Check: Replace getServerSideProps/getStaticProps with async components
│  ├─ Check: Convert _app.tsx and _document.tsx to layout.tsx
│  ├─ Check: Update data fetching to use fetch() with caching options
│  ├─ Codemod: npx @next/codemod@latest
│  └─ Load: ./references/framework-upgrades.md
│
├─ Vue 2 → 3
│  ├─ Check: Replace Options API with Composition API (optional but recommended)
│  ├─ Check: Replace Vuex with Pinia
│  ├─ Check: Replace event bus with mitt or provide/inject
│  ├─ Check: Update v-model syntax (modelValue prop)
│  ├─ Tool: Migration build (@vue/compat) for incremental migration
│  └─ Load: ./references/framework-upgrades.md
│
├─ Laravel 12 → 13
│  ├─ Check: PHP 8.3 is now the minimum (8.5 supported)
│  ├─ Check: Cache/Redis key prefixes now use hyphenated suffixes
│  ├─ Check: Adopt native PHP attributes (models, jobs, controllers) — optional
│  ├─ Check: Queue routing by class via Queue::route(...) — optional
│  ├─ Tool: laravel shift (automated upgrade service)
│  └─ Load: ./references/framework-upgrades.md (covers 10→11 in depth; 12→13 is near zero-break)
│
├─ Angular (any major version)
│  ├─ Check: Run ng update for guided migration
│  ├─ Check: Review Angular Update Guide (update.angular.io)
│  ├─ Tool: ng update @angular/core @angular/cli
│  └─ Load: ./references/framework-upgrades.md
│
└─ Django (any major version)
   ├─ Check: Run python -Wd manage.py test for deprecation warnings
   ├─ Check: Review Django release notes for removals
   ├─ Tool: django-upgrade (automatic fixer)
   └─ Load: ./references/framework-upgrades.md

Dependency Audit Workflow

Ecosystem?
│
├─ JavaScript / Node.js
│  ├─ npm audit / npm audit fix
│  ├─ npx audit-ci --moderate (CI integration)
│  └─ Socket.dev for supply chain analysis
│
├─ Python
│  ├─ pip-audit
│  ├─ safety check
│  └─ pip-audit --fix (auto-update vulnerable packages)
│
├─ Rust
│  ├─ cargo audit
│  └─ cargo deny check advisories
│
├─ Go
│  ├─ govulncheck ./...
│  └─ go list -m -u all (list available updates)
│
├─ PHP
│  ├─ composer audit
│  └─ composer outdated --direct
│
└─ Multi-ecosystem
   └─ Trivy, Snyk, or Dependabot across all

Pre-Migration Checklist

[ ] Test coverage measured and documented (target: >70% for critical paths)
[ ] CI pipeline green on current version
[ ] All dependencies up to date (or pinned with rationale)
[ ] Database backup taken (if applicable)
[ ] Git state clean — migration branch created from latest main
[ ] Rollback plan documented and tested
[ ] Breaking change list reviewed from upstream changelog
[ ] Team notified of migration window
[ ] Feature flags in place for gradual rollout (if applicable)
[ ] Monitoring and alerting configured for regression detection
[ ] Performance baseline captured (response times, memory, CPU)
[ ] Lock file committed (package-lock.json, yarn.lock, Cargo.lock, etc.)

Breaking Change Detection Patterns

How do you detect breaking changes?
│
├─ Semver Analysis
│  ├─ Major version bump → breaking changes guaranteed
│  ├─ Check CHANGELOG.md or BREAKING_CHANGES.md in repo
│  └─ npm: npx npm-check-updates --target major
│
├─ Changelog Parsing
│  ├─ Search for: "BREAKING", "removed", "deprecated", "renamed"
│  ├─ GitHub: compare releases page between versions
│  └─ Read migration guide if one exists
│
├─ Compiler / Runtime Warnings
│  ├─ Enable all deprecation warnings before upgrading
│  ├─ Python: python -Wd (turn deprecation warnings to errors)
│  ├─ Node: node --throw-deprecation
│  └─ TypeScript: strict mode catches type-level breaks
│
├─ Codemods (automated detection + fix)
│  ├─ jscodeshift — JavaScript/TypeScript AST transforms
│  ├─ ast-grep — language-agnostic structural search/replace
│  ├─ rector — PHP automated refactoring
│  ├─ gofmt / gofumpt — Go formatting changes
│  └─ 2to3 — Python 2 to 3 (legacy)
│
└─ Type Checking
   ├─ TypeScript: tsc --noEmit catches API shape changes
   ├─ Python: mypy / pyright after upgrade
   └─ Go: go vet ./... after upgrade

Codemod Quick Reference

Rollback Strategy Decision Tree

Migration failed or caused issues — how to roll back?
│
├─ Code-only change, no data migration
│  ├─ Small number of commits
│  │  └─ Git Revert
│  │     git revert --no-commit HEAD~N..HEAD && git commit
│  │     Pros: clean history, safe for shared branches
│  │     Cons: merge conflicts if code has diverged
│  │
│  └─ Entire feature branch
│     └─ Revert merge commit
│        git revert -m 1 <merge-commit-sha>
│
├─ Feature flag controlled
│  └─ Toggle flag off
│     Instant rollback, no deployment needed
│     Keep old code path until new path is proven
│
├─ Database schema changed
│  ├─ Reversible migration exists
│  │  └─ Run down migration
│  │     rails db:rollback / php artisan migrate:rollback / alembic downgrade
│  │
│  └─ Irreversible migration (dropped column, changed type)
│     └─ Restore from backup + replay write-ahead log
│        This is why you take backups BEFORE migration
│
└─ Infrastructure / deployment
   ├─ Blue-Green deployment
   │  └─ Switch traffic back to blue (old) environment
   │
   ├─ Canary deployment
   │  └─ Route 100% traffic back to stable version
   │
   └─ Container orchestration (K8s)
      └─ kubectl rollout undo deployment/app

Common Gotchas

Reference Files

Staleness verifier

This skill hardcodes specific framework/language target versions (React 19, Laravel 13, Python 3.14, Node 26, TypeScript 6, Go 1.26, Rust 2024, PHP 8.5). scripts/check-migrate-facts.py guards them against silent drift:

# Structural (PR CI, no network): every catalogued target version still appears
# where it is recorded (description vs body), and the currency note carries a year.
python scripts/check-migrate-facts.py --offline        # exit 0 consistent, 10 drift

# Live (freshness job, never blocks a PR): each target is resolved against
# endoflife.date (python/nodejs/laravel/php/go) and npm (react/typescript).
python scripts/check-migrate-facts.py --live            # exit 10 a target lags latest, 7 unreachable

The canonical target-version list lives in assets/migrate-facts.json; when you change a recommended target, update it to match or --offline fails CI. A --live drift means the skill is naming an older target than the ecosystem's current stable — review, don't auto-rewrite.

See Also