migration-plan

Start with an impact analysis that maps all affected files and dependencies, then break the work into phased, independently deployable steps. Each step should have a risk rating, reversibility note, and verification checkpoint before execution begins.

A migration plan should include an overview of current and target states, impact analysis, prerequisites, phased steps with risk levels, breaking changes, a rollback strategy, a testing strategy, and timeline estimates. The rollback strategy is the most critical section.

Incremental migration is preferred whenever possible because each step stays independently deployable and reversible. Big-bang approaches concentrate risk and make rollback difficult, so reserve them for cases where incremental paths genuinely do not exist.

Flag any irreversible step explicitly in the plan and define the point after which rollback is no longer possible. Use backups, expand-and-contract schema patterns, and feature flags to keep destructive changes recoverable for as long as possible.

Skip the full planning process for small, localized changes with obvious scope and easy reverts, where the planning overhead exceeds the risk. The plan format is designed for cross-cutting work like framework upgrades, database swaps, and API versioning.