Skip to content
Skills Library
DevOps & cloud · Planning

migration-engineering

/migration-engineering

Plan and execute safe cross-system migrations, including service extraction from monoliths. Use when moving data, schemas, interfaces, infrastructure, or service ownership through compatibility windows, dual-running, reconciliation, cutover, recovery, or deprecation. Do not use for deciding whether decomposition is justified, designing a target architecture, or implementing one named technology; route those to the relevant architecture or specialist skill.

Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
14
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Plan and execute safe cross-system migrations, including service extraction from monoliths. Use when moving data, schemas, interfaces, infrastructure, or service ownership through compatibility windows, dual-running, reconciliation, cutover, recovery, or deprecation. Do not use for deciding whether decomposition is justified, designing a target architecture, or implementing one named technology; route those to the relevant architecture or specialist skill.

Original author description

Plan and execute safe cross-system migrations, including service extraction from monoliths. Use when moving data, schemas, interfaces, infrastructure, or service ownership through compatibility windows, dual-running, reconciliation, cutover, recovery, or deprecation. Do not use for deciding whether decomposition is justified, designing a target architecture, or implementing one named technology; route those to the relevant architecture or specialist skill.

How it works

  1. When to use
  2. When not to use
  3. Core workflow
  4. Loading guide
  5. Specialist routing
Original SKILL.md headings · 179 lines, 1,349 words
SKILL.md preview
---
name: migration-engineering
description: >-
  Plan and execute safe cross-system migrations, including service extraction
  from monoliths. Use when moving data, schemas, interfaces, infrastructure, or
  service ownership through compatibility windows, dual-running, reconciliation,
  cutover, recovery, or deprecation. Do not use for deciding whether
  decomposition is justified, designing a target architecture, or implementing
  one named technology; route those to the relevant architecture or specialist
  skill.
license: MIT
compatibility: Platform-agnostic methodology. No runtime dependencies, API keys, or external services required.
metadata:
  tags: migration-engineering, data-migration, schema-migration, api-migration,
    infrastructure-migration, service-migration, expand-contract, compatibility-window,
    dual-running, backfill, reconciliation, cutover, deprecation, rollback,
    roll-forward, irreversible-migration
---

# 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:

| Trigger | Example |
|---|---|
| A schema change that must not break existing readers or writers | "Add a non-nullable column to a high-traffic table with zero downtime" |
| A data migration between stores or representations | "Migrate user profiles from Postgres to a dedicated service with its own database" |
| An API version migration with a deprecation window | "Move consumers from v1 REST to v2 GraphQL over six months" |
| An infrastructure or service migration | "Shift a workload from self-hosted VMs to a managed platform across regions" |
| A cross-system change requiring dual-running and reconciliation | "Replace the legacy billing engine with a new one while keeping both in sync" |
| Planning cutover, rollback, or irreversible steps for a migration | "Define the recovery strategy for the warehouse schema migration" |

## 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](../data-engineering/SKILL.md)
  for a simple DDL change, [api-design-and-evolution](../api-design-and-evolution/SKILL.md)
  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](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](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](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](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.

| File | Load when |
|---|---|
| [references/discovery-brief.md](references/discovery-brief.md) | You need to understand how migration concepts map across sibling skills and where this skill's boundaries are |
| [references/migration-types.md](references/migration-types.md) | Classifying a migration (schema, data, API, infrastructure/service, service extraction) before selecting patterns |
| [references/compatibility-patterns.md](references/compatibility-patterns.md) | Designing forward/backward compatibility for a specific migration type |
| [references/recovery-classification.md](references/recovery-classification.md) | Classifying recovery paths (rollback, roll-forward, restore, irreversible) for a concrete migration step |
| [references/planning-fields.md](references/planning-fields.md) | Drafting or reviewing the structured planning fields (reconciliation, evidence, observability, customer impact, ownership) a plan must address |
| [references/service-extraction-patterns.md](references/service-extraction-patterns.md) | Assessing extraction seams and selecting strangler routing, branch by abstraction, anti-corruption, CDC, and parallel-run patterns; includes modular-monolith retention criteria |
| [templates/migration-plan.md](templates/migration-plan.md) | Producing a complete migration plan with all structured fields |
| [templates/compatibility-matrix.md](templates/compatibility-matrix.md) | Building a compatibility matrix for a multi-consumer migration |
| [templates/reconciliation-plan.md](templates/reconciliation-plan.md) | Designing a reconciliation strategy for a data migration |
| [templates/cutover-and-recovery-record.md](templates/cutover-and-recovery-record.md) | Recording cutover procedures, recovery paths, and irreversible-step acknowledgments |
| [templates/service-extraction-assessment.md](templates/service-extraction-assessment.md) | Capturing boundary evidence, coupling, ownership, coexistence, sequencing, operational risk, reversibility, and the decision to extract or retain a modular monolith |

## Specialist routing

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

| Migration concern | Route to |
|---|---|
| Decomposition justification and target-boundary decision | [`software-architecture`](../software-architecture/SKILL.md); this skill sequences an authorized transition |
| API contract design, versioning policy, deprecation mechanics | [api-design-and-evolution](../api-design-and-evolution/SKILL.md) |
| Database schema evolution, ETL/ELT pipeline design, backfill operations | [data-engineering](../data-engineering/SKILL.md) |
| Infrastructure provisioning, service networking, secret management during migration | [platform-engineering](../platform-engineering/SKILL.md) |
| Release sequencing, progressive delivery, canary rollout, artifact promotion | [release-engineering](../release-engineering/SKILL.md) |
| SLO definition, error budgets, operational readiness, incident response during migration | [site-reliability-engineering](../site-reliability-engineering/SKILL.md) |
| Work breakdown, dependency mapping, critical path, ownership assignment | [implementation-planning](../implementation-planning/SKILL.md) |
| Threat modeling, security review of migration surface, auth boundary changes | [secure-software-engineering](../secure-software-engineering/SKILL.md) |
| Test strategy, regression coverage, verification gates during migration | [qa-methodology](../qa-methodology/SKILL.md) |
| Verification verdicts, evidence standards, boundary testing | [verification-methodology](../verification-methodology/SKILL.md) |

### 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.
Files in this package (14)
  • README.md 6 KB
  • SKILL.md 12 KB
  • evals/evals.json 16 KB
  • references/compatibility-patterns.md 4 KB
  • references/discovery-brief.md 12 KB
  • references/migration-types.md 4 KB
  • references/planning-fields.md 2 KB
  • references/recovery-classification.md 5 KB
  • references/service-extraction-patterns.md 10 KB
  • templates/compatibility-matrix.md 2 KB
  • templates/cutover-and-recovery-record.md 2 KB
  • templates/migration-plan.md 3 KB
  • templates/reconciliation-plan.md 1 KB
  • templates/service-extraction-assessment.md 6 KB

Versions

The database has no other skills named migration-engineering.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version ff84fa742918 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100adobe-migration-deep-dive
    Analyze and execute a multi-workload migration into or across Adobe services with contract evidence, dependency waves, dual-run reconciliation, cost controls, and rollback. Use when the task requires adobe platform migration program. Trigger with "Adobe migration plan", "move…
  • 90integration-migration
    Move between API versions or providers without downtime, using parallel running and staged cutover. Use when a provider deprecates a version or you are replacing a service.
  • 90aws-migration-cutover-architect
    Plan, review, and de-risk AWS migrations and cutovers across discovery, dependency mapping, wave planning, AWS Application Migration Service, Migration Hub, test launches, acceptance tests, downtime windows, rollback, DNS, data consistency, and post-cutover validation. Use for…
  • 100migration-architect
    Zero-downtime migration planning, compatibility validation, and rollback strategy generation. Tools for system, database, and infrastructure migrations with minimal business impact. Use when planning a database migration, infrastructure cutover, system replacement, or any…
  • 100migration-architect
    Plans zero-downtime migrations with compatibility validation, rollback strategies, and phased execution plans. Use when migrating databases, APIs, infrastructure, or services between platforms or versions.
  • 100generation-upgrade-acceptance
    Plan and verify parameterized source-to-target upgrades through manual or pipeline execution, immutable main-based releases, fresh deployment, reconciliation, restore drills, incident regression, and a fix-PR-release-retest loop. Use for generation replacement and pre-cutover…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.