Review Packet: Migration
When to use
Use this packet for framework migrations, SPA-to-hybrid moves, module restructuring, design-system adoption, state management replacement, build tool changes, or routing/data architecture changes.
Intake questions
- What problem does the migration solve?
- What user or business risk exists if nothing changes?
- What must remain compatible during the transition?
- Which teams, routes, packages, and release pipelines are affected?
- What is the smallest reversible slice?
- How will old and new systems coexist?
- What metric proves the migration is succeeding?
Required artifacts
- Current and target architecture diagrams.
- Migration slice plan.
- Compatibility and coexistence policy.
- Risk register.
- Rollback plan.
- Success metric dashboard.
Decision matrix
| Situation | Prefer |
|---|---|
| High risk, broad surface | Strangler migration with route or feature slices. |
| Low user visibility | Internal package migration with compatibility adapters. |
| Tooling replacement | Dual-run checks and staged adoption. |
| Design-system migration | Component-by-component adoption with deprecation windows. |
Red flags
- Migration is justified only by novelty.
- The team plans a big-bang rewrite.
- Success is measured by percent migrated instead of user/system outcomes.
- Compatibility adapters have no removal plan.
- Product roadmap and migration capacity are not reconciled.
Approval criteria
- Current pain and target outcome are explicit.
- Slice plan limits blast radius.
- Coexistence rules are clear.
- Rollback and freeze criteria exist.
- Debt created by the migration has owner and expiry.
Example reviewer comments
- "This migration needs a route-by-route plan; package replacement alone does not control user risk."
- "The adapter is acceptable only if it has a removal milestone and owner."
- "Please define the metric that proves this improved delivery, performance, or reliability."
Example ADR prompt
Write an ADR explaining why migration is needed, why the target is selected, alternatives rejected, coexistence plan, risks, rollback, and success measures.
Release readiness checklist
- First slice is reversible.
- Compatibility tests exist.
- Product owners understand delivery impact.
- Monitoring compares old and new paths.
- Migration debt register exists.