magnus919_agent-skills/migration-engineering/references/discovery-brief.md

Discovery Brief — Migration Engineering

Purpose

This brief surveys existing migration-adjacent material in the agent-skills catalog, identifies overlaps and gaps, and defines the ownership boundary for the migration-engineering skill. It answers: what does this skill own, and what does it deliberately hand off to others?

Existing migration-adjacent material in the catalog

api-design-and-evolution — API versioning and deprecation

api-design-and-evolution covers API compatibility assessment, versioning policy, deprecation mechanics, and the consumer-impact analysis of interface changes. Its deprecation-migration-plan template and evolution-and-deprecation reference define how a single API evolves.

What migration-engineering adds: API evolution owns the single-interface change. Migration-engineering owns the cross-system migration where the API change is one component of a larger transition — for example, a service extraction where the API changes, the data moves, and the infrastructure shifts simultaneously. Migration-engineering also adds the recovery-path classification (rollback/roll-forward/restore/irreversible) that API evolution does not address, and the structured reconciliation and correctness-evidence fields.

Boundary: API design owns the contract. Migration engineering owns the plan that coordinates the contract change with data, infrastructure, and service changes. When a migration involves only an API version bump with no data movement or infrastructure change, the api-design-and-evolution deprecation workflow is sufficient — migration-engineering is not needed.

data-engineering — schema migration and ETL

data-engineering covers database schema evolution (its database-migrations reference), ETL/ELT pipeline design, data quality monitoring, and backup/recovery. Its zero-downtime migration patterns, versioned schemas, and test-first migrations are the authoritative source for database-level changes.

What migration-engineering adds: Data engineering owns the single-store schema change. Migration-engineering owns the cross-store migration — moving data between different stores, splitting a monolith database into services, or migrating ownership of data from one team to another. Migration-engineering also adds the migration-type classification (distinguishing schema, data, API, and infrastructure migrations), the expand/contract sequence as a general pattern, and the structured reconciliation fields that span beyond database-level comparisons.

Boundary: Data engineering owns the DDL, the backfill script, and the pipeline. Migration engineering owns the migration plan that sequences the DDL with the API change, the consumer migration, and the cutover. For a single-database schema change (e.g., add a nullable column), data-engineering's database-migrations reference covers it directly.

platform-engineering — infrastructure changes

platform-engineering covers infrastructure-as-code, container orchestration, service networking, and cloud platform operations. Its references on CI/CD pipelines and infrastructure-as-code define how platform changes are provisioned and deployed.

What migration-engineering adds: Platform engineering owns the how of infrastructure provisioning. Migration-engineering owns the when and in what order — the staging, the compatibility window, the traffic-shifting procedure, and the rollback decision points. Platform engineering provides the Terraform module or Helm chart; migration engineering provides the plan that says "apply this module to the staging environment first, verify SLOs for 48 hours, then promote to production with a 10% canary."

Boundary: Platform engineering owns the infrastructure definition and provisioning tooling. Migration engineering owns the migration plan that sequences the infrastructure change with other migration components. For a pure infrastructure change with no data or API component (e.g., upgrading a Kubernetes cluster version), platform-engineering and release-engineering together are sufficient.

release-engineering — rollout and change promotion

release-engineering covers progressive delivery (canaries, rings, percentage rollouts), feature flags, release readiness gates, rollback planning, and change governance. Its rollout mechanics are the execution engine for promoting changes through environments.

What migration-engineering adds: Release engineering owns the release pipeline — how artifacts move through stages. Migration engineering owns the migration staging — what each stage means for data consistency, consumer compatibility, and recovery. A release engineer can design a canary deployment; a migration engineer can design the dual-write period, the reconciliation gate, and the cutover trigger that the canary deployment gates on.

Boundary: Release engineering owns the promotion mechanics. Migration engineering owns the migration-specific gates and evidence requirements that feed into those mechanics. For a standard code deployment with no data or schema migration, release-engineering alone is sufficient.

site-reliability-engineering — change management

site-reliability-engineering covers SLO/SLI frameworks, error budgets, incident command, and operational change management. Its change-management practices define how operational risk is assessed and how changes are monitored in production.

What migration-engineering adds: SRE owns the operational safety of change — error budgets, SLO-based gating, and incident response. Migration engineering owns the migration-specific risk — compatibility breaks, reconciliation failures, and cutover timing. SRE provides the error budget that gates the migration; migration engineering provides the migration plan that stays within that budget.

Boundary: SRE owns the operational risk framework. Migration engineering owns the migration risk specific to the cross-system transition. For a change that is not a migration (no data movement, no interface change, no infrastructure shift), SRE change management covers it.

implementation-planning — migration planning

implementation-planning produces executable delivery plans for approved specifications: work breakdown, dependency mapping, critical path, ownership, sequencing, and rollout strategy. Its templates cover migration staging and rollback design as part of a broader delivery plan.

What migration-engineering adds: Implementation planning owns the delivery plan structure — who does what, in what order, with what dependencies. Migration engineering owns the migration-specific content that fills that structure — the compatibility matrix, the reconciliation design, the recovery-path classification, the cutover procedure. An implementation plan says "Week 3: backfill user profiles"; a migration plan says how to backfill, how to reconcile, what to do if reconciliation fails, and whether the backfill step is reversible.

Boundary: Implementation planning owns the work-breakdown and coordination structure. Migration engineering owns the migration domain knowledge that populates the structure. They are complementary, not competing. A migration plan produced by this skill is a structured input to an implementation plan produced by implementation-planning.

product-lifecycle-learning — retirement and sunset

product-lifecycle-learning covers feature and product retirement: deprecation, migration paths for customers, customer treatment during sunset, and retained reusable learning. Its retirement-lifecycle reference and sunset-plan template define the retirement decision and communication lifecycle.

What migration-engineering adds: Product-lifecycle-learning owns the decision to retire and the customer-treatment plan. Migration engineering owns the technical migration that executes the retirement — the data export, the API shutdown, the infrastructure decommissioning. Product-lifecycle-learning says "this feature retires in Q3 and customers must migrate to the replacement by Q4"; migration engineering says how to migrate the data, how to run the old and new in parallel during the transition, and how to verify the migration before shutting down the old system.

Boundary: Product-lifecycle-learning owns the retirement decision and customer communication. Migration engineering owns the technical execution of the retirement migration. They are sequential: the retirement decision triggers the migration plan.

Ownership boundary

What migration-engineering OWNS

1. Migration-type classification — distinguishing schema, data, API, and infrastructure/service migrations and their different compatibility, correctness, and recovery characteristics.
2. Expand/contract sequencing — the general pattern of adding the new alongside the old, maintaining a compatibility window, dual-running, and contracting by removing the old.
3. Compatibility window design — defining the duration, conditions, and consumer migration tracking for the period when old and new coexist.
4. Backfill strategy — selecting full, incremental, or streaming backfill and sequencing it with dual-writes.
5. Reconciliation design — defining how source and target are verified to match across completeness, accuracy, timeliness, and consistency.
6. Cutover procedure — the exact sequence, pre-conditions, observability signals, and interruption points for switching to the new system.
7. Recovery-path classification — distinguishing rollback, roll-forward, restore, and irreversible steps, and requiring explicit acknowledgment for irreversible steps.
8. Deprecation and cleanup — the timeline and procedure for removing the old system after migration is verified.
9. Structured planning fields — reconciliation, correctness evidence, observability, customer impact, and ownership as checklist/template items.
10. Cross-specialist coordination — routing implementation details to the domain specialist that owns each subsystem.

What migration-engineering HANDS OFF

1. API contract design and versioning policy → api-design-and-evolution. Migration engineering cites the API compatibility policy; it does not define it.
2. Database DDL, ETL pipeline implementation, backfill script authoring → data-engineering. Migration engineering defines the backfill strategy; data engineering implements it.
3. Infrastructure provisioning, Terraform modules, Helm charts → platform-engineering. Migration engineering defines the staging sequence; platform engineering provisions it.
4. Release pipeline mechanics, canary configuration, feature flag implementation → release-engineering. Migration engineering defines the migration gates; release engineering implements the promotion pipeline.
5. SLO definition, error budget policy, incident response procedure → site-reliability-engineering. Migration engineering consumes the error budget as a gate; SRE defines it.
6. Work breakdown, dependency mapping, critical path, ownership assignment → implementation-planning. Migration engineering provides the migration-specific content; implementation planning structures it into a delivery plan.
7. Threat modeling, security review of migration surface → secure-software-engineering.
8. Retirement decision and customer communication → product-lifecycle-learning. Migration engineering executes the technical side of a retirement-triggered migration.
9. Test strategy and verification gate design → qa-methodology and verification-methodology.