Generate structured migration plans with inventory, risk-ranked sequence, rollback procedures, and acceptance criteria for major upgrades or framework migrations. Use when upgrading major dependencies (React 17→18, Python 3.9→3.12), migrating frameworks (Express→Fastify, CRA→Vite), or scoping 'modernize the codebase' initiatives. Do not use for patch-level dependency updates or greenfield projects.
Turns "we need to upgrade X" into a methodical execution plan.
Identify all affected surfaces:
## Inventory: [Migration Name]
### Direct Dependencies
| Package | Current | Target | Breaking Changes |
|---------|---------|--------|------------------|
| [name] | [ver] | [ver] | [list] |
### Affected Files
- [path pattern] ([N] files) — [why affected]
### Integration Points
- CI/CD: [changes needed]
- Testing: [framework upgrade required?]
- Build tooling: [changes needed]
| Risk Level | Criteria | Examples |
|---|---|---|
| High | Core business logic, payment, auth, data persistence | Payment processing, auth flow |
| UI components, utilities with many dependents |
| Shared component library |
| Low | Dev tooling, test utilities, isolated features | Linter config, test helpers |
Order by: dependencies first, then risk (low → high):
### Migration Sequence
1. [ ] Update build tooling (low risk, unblocks others)
2. [ ] Migrate test utilities (enables validation of later stages)
3. [ ] Low-risk leaf components (build confidence)
4. [ ] Core utilities (high dependency count)
5. [ ] High-risk business logic (with extra validation)
### Rollback: Stage N
- Git: `git revert HEAD~N..HEAD`
- Dependencies: `npm ci` from lockfile at tag `pre-stage-N`
- Verification: `npm test && npm run e2e`
### Acceptance Criteria
- [ ] All existing tests pass (or intentional updates documented)
- [ ] No type errors introduced
- [ ] Bundle size delta < 5%
- [ ] Performance metrics maintained
- [ ] Manual QA of critical user flows
# Migration Pack: [Name] — [From] → [To]
## Summary
- Scope: [N] files, [N] packages
- Estimated effort: [X] days
- Risk level: [High/Medium/Low]
## Inventory
[tables from step 1]
## Migration Sequence
[ordered stages with checkboxes]
## Rollback Procedures
[per-stage rollback]
## Acceptance Criteria
[checklist]
## Known Issues & Workarounds
[documented blockers and solutions]