dev-migration-plan

name	dev-migration-plan
description	Use to plan modernization, framework upgrades, service extraction, schema migrations, rewrites, and rollback paths.
metadata	{"version":"0.6","updated":"2026-07-26"}

Migration plan workflow

Use this workflow when changing technology, framework, architecture, schema, or large old-system behavior must be planned safely.

When present, consume the SDLC-ADS state before planning:

• local/sdlc/_资产.md
• local/sdlc/架构.md for as-built and to-be architecture.
• local/sdlc/领域.md for ownership, data, allowed dependencies, and forbidden dependencies.
• current local/sdlc/<slug>/00-状态.md for lane, stage, decisions, blockers, and validation state.

For pure refactor or migration, prefer behavior baseline, as-built, to-be, phases, validation, and rollback. Do not require Product Pack material unless the migration changes user behavior, business semantics, permissions, data ownership, or release commitments.

Steps

1. Define target and non-goals.

   • What is being migrated
   • What must remain compatible
   • What can change
   • Constraints and deadlines

2. Map current behavior.

   • Entry points
   • Core business flows
   • Data model
   • External integrations
   • Tests and monitoring
   • Known risk areas
   • Existing as-built notes from 架构.md or repository evidence

3. Choose migration strategy.

   • Incremental replacement
   • Adapter/facade
   • Strangler pattern
   • Parallel run
   • Feature flag rollout
   • Backward-compatible schema transition
   • Architecture/domain constraint preservation
   • If the trade-off set is still contested, recommend $codex-next:core-grilling and stop. Wait for the user to invoke it explicitly; do not imitate or begin that workflow here.

4. Build safety rails.

   • Characterization tests
   • Contract tests
   • Data backup or rollback
   • Observability
   • Stop conditions
   • Behavior baseline for externally visible behavior
   • Dependency and ownership checks from 领域.md

5. Break into phases.

   • Small milestones
   • Validation after each phase
   • Rollback path
   • Owner and dependency assumptions

6. Update durable ADS only when needed.

   • New durable architecture constraints -> local/sdlc/架构.md
   • New ownership or dependency constraints -> local/sdlc/领域.md
   • New decisions or validation baseline -> local/sdlc/_资产.md
   • Current delivery state -> local/sdlc/<slug>/00-状态.md

Output

Return:

1. Current-state map
2. Target state
3. Phased migration plan
4. Validation and rollback strategy
5. ADS impact and durable state updates needed
6. Risks and open decisions

Do not

• Do not propose a big-bang rewrite unless explicitly requested.
• Do not ignore current behavior just because the old code is messy.
• Do not start implementation before the safety path is clear.
• Do not treat refactor/migration as a PRD problem unless product or domain semantics change.