Migration Engineering

Migration Engineering

Plan and execute safe migrations across system boundaries. A migration is any change that moves data, schemas, interfaces, infrastructure, or services from a current state to a target state while preserving correctness, availability, and recoverability during the transition.

This skill owns the cross-system migration method — compatibility design, staging, reconciliation, cutover, recovery, and deprecation. It does not own the implementation details of any single technology or subsystem; those belong to specialist skills.

When to use

Load this skill when the task involves:

When not to use

• Single-technology quick fixes — if the change is confined to one system with no compatibility window, no dual-running, and no cross-system coordination, use the relevant specialist skill directly (e.g., data-engineering for a simple DDL change, api-design-and-evolution for a single-endpoint deprecation).
• Tool-specific how-to guides — this skill provides the method, not vendor-specific instructions. It does not prescribe one migration technology, one database engine, one API gateway, or one infrastructure platform.
• Migrations without a system boundary — in-place refactors, code rewrites that don't cross a data or interface boundary, or single-service configuration changes are not migration-engineering scope.
• Guaranteeing rollback — this skill does not claim rollback is always possible. Some migrations include steps that are irreversible; the method requires identifying those steps explicitly and planning acceptance, communication, and contingency rather than implying a false safety net.

For service extraction, load references/service-extraction-patterns.md when a boundary has been proposed and the transition pattern, coexistence shape, or modular-monolith alternative needs assessment. Use templates/service-extraction-assessment.md to capture the evidence before filling the general migration plan. This skill sequences an approved extraction; it does not decide that a monolith should be split or identify the target architecture.

Core workflow

1. Classify and scope the migration

Determine which migration type(s) apply — real-world migrations often combine types (a service extraction includes both a data migration and an API migration). Document the current state, target state, boundary being crossed, type(s) with their compatibility requirements, and affected systems, teams, and consumers. Load references/migration-types.md for the classification of schema, data, API, infrastructure/service, and service-extraction migrations.

2. Design the expand/contract sequence

The expand/contract pattern is the foundational safe-migration primitive:

1. Expand — add the new interface, schema, or system while the old one continues to serve; both coexist, and existing consumers are unaffected.
2. Compatibility window — a defined period during which both old and new are available, with an explicit end condition (date, metric threshold, or event such as all registered consumers confirmed).
3. Dual-running or parallel operation — for data and service migrations, both systems operate concurrently (dual writes, dual reads with comparison), producing the evidence needed for the cutover decision.
4. Contract — remove the old interface after the window closes and verification confirms correctness and completeness.

Not every migration uses all four phases: an additive schema change may need only the expand phase; a complex service extraction uses all four.

3. Plan the backfill and reconciliation

For data migrations, choose a backfill strategy — full, incremental, or streaming (CDC/event log). Reconciliation verifies source and target match on four dimensions — completeness, accuracy, timeliness, and consistency — runs continuously during the compatibility window, and must pass before cutover; a reconciliation failure is a stop condition.

4. Design the cutover

Define the exact procedure (automated where possible, with pre/post conditions), the window and acceptable downtime, interruption points where the cutover can be paused or reversed (a cutover with none is a risk to flag explicitly), and the observability that confirms progress and triggers abort.

5. Define recovery paths

Every migration step has exactly one of four recovery classifications — never conflate them: rollback (undo the change), roll-forward (fix forward in the new state), restore (recover from backup/snapshot), and irreversible (no reversal possible at any level). Irreversible steps require explicit acknowledgment before execution; distinguish "we chose not to build a reversal path" from "reversal is physically impossible." Both require acceptance, communication, and contingency. Load references/recovery-classification.md when classifying concrete steps.

6. Plan deprecation and cleanup

After verified cutover: define the deprecation window for the old system in read-only/degraded mode, track which consumers still depend on the old interface, remove old schemas/code paths/flags/configuration/credentials/ infrastructure, and communicate at each stage (window opens, cutover scheduled, cutover complete, window closing, removal).

7. Verify and close

Before declaring completion, collect correctness evidence (reconciliation reports, consumer verification, error-rate comparisons, SLO compliance), confirm observability shows the expected steady state, verify recovery procedures were tested and irreversible steps acknowledged, and obtain owner sign-off per phase.

Loading guide

Load references and templates on demand — do not load everything at once.

Specialist routing

Migration engineering composes domain specialists — it never duplicates their methodology. Route implementation details to the skill that owns the subsystem.

Routing to same-wave and future skills

Migration evidence — reconciliation reports, cutover records, recovery-path classifications, and deprecation tracking — feeds production-readiness assessments. The production-readiness skill consumes migration plans as evidence that a service is ready for production operation.

The production-excellence bundle composes migration-engineering alongside production-readiness, resilience-and-recovery, capacity-and-cost-engineering, incident-learning, and privacy-engineering. Migration-engineering contributes the safe-change dimension to the production-excellence lifecycle.

Routing to product-lifecycle skills

When a migration is triggered by a feature retirement or product sunset, coordinate with product-lifecycle-learning for the retirement decision record, deprecation timeline, and customer-treatment plan.