{
  "schema_version": 1,
  "skill_name": "migration-engineering",
  "evals": [
    {
      "id": "additive-schema-change",
      "prompt": "Plan a migration to add a non-nullable 'status' column with a default value to a high-traffic 'orders' table in PostgreSQL. The table receives 10,000 writes per minute. Zero downtime is required. Existing readers and writers must not be affected during the change.",
      "expected_output": "An expand-phase plan: add the column as nullable first (or with a default that Postgres can apply without rewriting the table), populate existing rows, then add the NOT NULL constraint. Identifies the expand phase as purely additive with no contract phase needed. Distinguishes between Postgres versions where adding a column with a default causes a table rewrite vs. versions where it is metadata-only. No dual-running or backfill is needed because this is a single-table schema change. The plan notes that this change is fully rollback-able (drop column or remove constraint). Includes observability: lock duration, replication lag, and write throughput during the migration.",
      "assertions": [
        "Describes the expand phase as adding the column without breaking existing readers or writers.",
        "Identifies the Postgres version-specific behavior of adding columns with defaults.",
        "Classifies recovery as rollback (the change is additive and reversible).",
        "Includes observability signals: lock duration, replication lag, write throughput.",
        "States that no contract phase is needed for this purely additive change.",
        "Does not propose dual-running or backfill for a single-table schema change."
      ]
    },
    {
      "id": "backfill-with-reconciliation",
      "prompt": "Plan a migration to move user profile data (10 million rows) from a monolithic Postgres database to a dedicated user-profile service with its own database. Both systems must remain operational during the transition. After cutover, the old profiles table will be dropped. The business requires that no user profile data is lost or corrupted during the migration.",
      "expected_output": "A dual-run/backfill plan with reconciliation. Phases: (1) deploy new user-profile service writing to its own database, (2) full backfill of existing 10M rows from Postgres to the new service, (3) enable dual-writes so new profile updates go to both systems, (4) continuous reconciliation comparing source and target for completeness, accuracy, timeliness, and consistency, (5) after reconciliation passes for a defined period, cut over reads to the new service, (6) after a verification window, stop dual-writes, (7) drop old profiles table. The plan includes rollback at each stage: before cutover, rollback is reversing the read switch; after cutover but before dropping old table, rollback is reverting reads to the old table. Dropping the old table is identified as an irreversible step that requires explicit acknowledgment.",
      "assertions": [
        "Describes a full backfill of 10M rows followed by dual-writes.",
        "Includes continuous reconciliation across completeness, accuracy, timeliness, and consistency dimensions.",
        "Identifies cutover read-switch as a distinct phase gated on reconciliation passing.",
        "Classifies pre-drop rollback as possible (revert reads to old table).",
        "Identifies dropping the old profiles table as an irreversible step.",
        "Requires explicit acknowledgment before the irreversible drop step.",
        "Describes observability: rows migrated, reconciliation drift, dual-write latency."
      ]
    },
    {
      "id": "api-version-migration",
      "prompt": "Plan a migration to move consumers from a REST v1 API to a GraphQL v2 API for an e-commerce product catalog. 200 external partners integrate with v1. The v1 API must remain available for 12 months after v2 launch. No partner should experience a breaking change without at least 6 months notice. Partners who migrate to v2 early should see no degradation.",
      "expected_output": "An expand/contract API migration plan. Expand phase: deploy v2 GraphQL API alongside v1 REST. Compatibility window: 12 months minimum, with consumer migration tracking per partner. Define what 'migrated' means per partner (e.g., zero v1 traffic for 30 consecutive days). Deprecation: announce v1 deprecation at 6 months, with a hard shutdown date at 12 months. Recovery: v1 remains available throughout the window, so rollback at any point means canceling the deprecation notice. V1 removal at 12 months is a potentially irreversible step if v1 cannot be redeployed — plan must address this. Observability: per-partner traffic by API version, migration-completion dashboard, error-rate comparison between v1 and v2.",
      "assertions": [
        "Describes expand phase: deploy v2 alongside v1 without removing v1.",
        "Defines a compatibility window with an explicit duration (12 months) and consumer migration tracking.",
        "Defines what 'migrated' means per consumer (e.g., zero v1 traffic for N days).",
        "Classifies v1 deprecation as reversible (cancel the notice) during the compatibility window.",
        "Addresses that v1 removal at end-of-window may be irreversible if redeployment is not possible.",
        "Includes observability: per-partner traffic by version, migration dashboard, error-rate comparison.",
        "Addresses customer impact: partners get 6 months notice before any breaking change."
      ]
    },
    {
      "id": "irreversible-cutover",
      "prompt": "Plan a migration to replace an on-premises hardware security module (HSM) with a cloud-based key management service (KMS). The HSM is being physically decommissioned — once powered off and shipped back to the vendor, it cannot be restored. All cryptographic keys must be migrated. The business requires zero unavailability of signing services during the transition.",
      "expected_output": "A migration plan that explicitly identifies the HSM decommissioning as an irreversible step. The plan includes: (1) key export/replication to the cloud KMS while HSM is still operational, (2) dual-running where both HSM and KMS can serve signing requests, (3) gradual traffic shift to KMS with per-key verification, (4) a defined observation period where KMS handles production signing traffic, (5) after verification, the physical HSM decommissioning step marked as IRREVERSIBLE with explicit acceptance criteria, stakeholder sign-off, and a contingency plan. Recovery classification: before HSM decommissioning, rollback is possible (shift traffic back to HSM); after decommissioning, the situation is irreversible — if the KMS fails, the contingency is a disaster-recovery KMS instance, not a rollback. The plan must NOT claim rollback is possible after decommissioning.",
      "assertions": [
        "Explicitly identifies HSM physical decommissioning as an irreversible step.",
        "Distinguishes recovery before decommissioning (rollback possible) from after (irreversible).",
        "Requires explicit acceptance criteria and stakeholder sign-off for the irreversible step.",
        "Includes a contingency plan for the irreversible state (DR KMS instance).",
        "Does NOT claim rollback is always possible or that the HSM can be restored after decommissioning.",
        "Describes observability: per-key signing verification, traffic-shift percentage, signing latency.",
        "Classifies recovery paths using all four categories: rollback (pre-decommissioning), restore (key restoration from backup if available), roll-forward (fix KMS configuration), and irreversible (HSM decommissioning)."
      ]
    },
    {
      "id": "reconciliation-failure",
      "prompt": "Plan a migration to move financial transaction data (500 million rows) from an Oracle database to a new PostgreSQL-based ledger service. Mid-migration, reconciliation detects that 0.3% of migrated rows have a mismatch in the 'amount' column — the source shows one value and the target shows another. The business requires zero data loss for financial transactions. The migration owner asks whether to proceed with cutover and fix the mismatches later.",
      "expected_output": "The plan must STOP on the reconciliation failure. It must NOT proceed with cutover. The response must: (1) identify the reconciliation failure as a hard stop condition, (2) diagnose possible causes (e.g., type-conversion error in the backfill script, timezone handling in timestamps that affected amounts, a race condition in the CDC pipeline), (3) prescribe a fix-forward procedure: pause the backfill, correct the root cause, re-reconcile the affected rows, and re-run reconciliation until it passes for 100% of the population, (4) escalate the decision to proceed despite reconciliation failure to the migration owner with explicit risk documentation, (5) state that proceeding with cutover while reconciliation is failing violates the correctness evidence requirement. The plan must NOT recommend or describe how to proceed with cutover while the mismatch exists. Claims are scoped to the harness, model, fixtures, and revision under test.",
      "assertions": [
        "Identifies reconciliation failure as a hard stop condition — cutover must not proceed.",
        "Diagnoses possible causes of the mismatch (type conversion, timezone, race condition).",
        "Prescribes a fix-forward procedure: pause, correct root cause, re-reconcile, re-verify.",
        "Escalates the decision to proceed despite failure to the migration owner with risk documentation.",
        "Does NOT describe or recommend proceeding with cutover while reconciliation is failing.",
        "States that correctness evidence (reconciliation passing) is a prerequisite for cutover.",
        "Includes observability for the reconciliation failure: mismatch rate, affected rows, error distribution."
      ]
    },
    {
      "id": "service-extraction-seam",
      "prompt": "We want to extract checkout pricing from a modular monolith into a separately deployed service. Pricing shares a transaction with order creation, five internal jobs read its tables directly, and no team owns the pricing data end to end. Assess whether to proceed and, if appropriate, outline the first migration steps.",
      "expected_output": "An evidence-first assessment that does not assume extraction is correct. It identifies shared transaction and data-ownership gaps, hidden direct consumers, and the need for a stable boundary and failure analysis. It either recommends retaining or strengthening the modular monolith pending evidence, or states concrete conditions before extraction; it does not jump directly to service creation.",
      "assertions": [
        "Identifies shared transaction scope as a boundary risk.",
        "Identifies unclear data ownership and direct table consumers as blockers or evidence gaps.",
        "Does not assume that a separately deployed service is the right outcome.",
        "Records explicit conditions or evidence needed before proceeding.",
        "Keeps decomposition justification distinct from migration sequencing."
      ]
    },
    {
      "id": "service-extraction-pattern-choice",
      "prompt": "An approved customer-notification extraction has a stable HTTP entry point, one source database, and a target service that can consume a change stream. We need no customer-visible downtime and want a reversible transition. Compare strangler routing, branch by abstraction, anti-corruption boundary, CDC, and parallel run, then select a primary and supporting sequence.",
      "expected_output": "A role-specific pattern comparison followed by a staged choice, likely routing or abstraction for traffic control with CDC for data synchronization and shadow or parallel comparison where side effects are isolated. The plan distinguishes what each pattern does, preserves the old authority during evidence collection, and states gates and reversal points.",
      "assertions": [
        "Distinguishes routing, abstraction, translation, CDC, and parallel execution rather than treating them as synonyms.",
        "Selects a primary transition pattern and names supporting patterns with reasons.",
        "Uses a compatibility window with the old path still selectable.",
        "Addresses CDC lag, ordering, duplicates, replay, and deletes.",
        "Defines comparison evidence and a stop or abort condition.",
        "Describes a reversible pre-cutover recovery path."
      ]
    },
    {
      "id": "service-extraction-data-authority",
      "prompt": "We are moving account preferences from a monolith database to a profile service. The monolith remains the authoritative writer during a six-week coexistence period; CDC feeds the new store, updates can arrive out of order, and deletes must propagate. Write the migration evidence and cutover gates.",
      "expected_output": "A migration record that states source authority, CDC ordering and replay behavior, duplicate and delete handling, lag monitoring, reconciliation across completeness, accuracy, timeliness, and consistency, and a cutover gate that does not transfer ownership until evidence passes. It distinguishes a read switch from a write-ownership transfer.",
      "assertions": [
        "States that the monolith remains authoritative during coexistence.",
        "Addresses out-of-order changes, duplicates, replay, and delete propagation.",
        "Includes CDC lag and error observability.",
        "Includes reconciliation across completeness, accuracy, timeliness, and consistency.",
        "Defines a cutover gate before changing write authority.",
        "Does not claim that switching reads alone transfers data ownership."
      ]
    },
    {
      "id": "service-extraction-recovery",
      "prompt": "During a service extraction, 20% of reads have moved to the new service. The old service is still writable and the old database has not been deleted. The new service shows a small semantic mismatch and elevated latency. Classify the recovery and state whether to continue shifting traffic.",
      "expected_output": "A stop or pause decision: do not continue shifting traffic while correctness and latency evidence are outside the agreed gates. Because the old service and database remain current and selectable, classify recovery as rollback by shifting reads back, then diagnose and reconcile before retrying. The response must not call this irreversible or recommend proceeding with known mismatch.",
      "assertions": [
        "Stops or pauses further traffic shifting because correctness and latency gates are failing.",
        "Classifies the available recovery as rollback while the old path remains current and selectable.",
        "Proposes mismatch diagnosis and re-verification before retrying.",
        "Does not classify the state as irreversible.",
        "Does not recommend proceeding with known semantic divergence."
      ]
    },
    {
      "id": "modular-monolith-near-boundary",
      "prompt": "A team asks to extract reporting because deployments feel slow. The candidate has no independent data owner, requires joins across four modules, has low and stable load, and would add a cross-service transaction for every report request. Produce a migration-engineering recommendation.",
      "expected_output": "A recommendation to retain or improve the modular monolith rather than create a service. It cites the absence of independent ownership, cross-module joins and transactions, low scale pressure, and added distributed failure/latency as evidence. It proposes modular improvements and states what evidence would reopen extraction.",
      "assertions": [
        "Recommends retaining or strengthening a modular monolith.",
        "Cites unclear ownership and cross-module transaction or join coupling.",
        "Uses low stable load as evidence against a service-specific scaling benefit.",
        "Explains the added latency or partial-failure risk of extraction.",
        "Defines a modular improvement and a condition for reassessment.",
        "Does not select a migration pattern merely because extraction was requested."
      ]
    }
  ]
}

# Compatibility Patterns

Detailed patterns for forward and backward compatibility by migration type.
Load this reference when designing the compatibility surface for a specific
migration.

## Schema compatibility

### Forward compatibility (old readers, new writers)

Old readers must be able to consume data written by the new schema. This is the
more common constraint: you control the writer deployment but cannot upgrade
every reader simultaneously.

**Patterns:**
- Add columns as nullable or with defaults. Old readers ignore unknown columns.
- Never rename a column in place. Add the new column, dual-write both old and
  new names during the compatibility window, then drop the old column after all
  readers have migrated.
- Never change a column type in place. Add a new column with the target type,
  dual-write to both, migrate readers, backfill the new column from the old,
  then drop the old column.
- Use views or computed columns to present a stable interface while the
  underlying schema changes.

### Backward compatibility (new readers, old writers)

New readers must be able to consume data written by the old schema. This applies
when readers are deployed before writers or when you cannot control writer
upgrade order.

**Patterns:**
- New readers treat new columns as optional. Missing columns must not cause
  errors.
- New readers must handle the old enum values, old units, old precision.
- Consider a compatibility adapter layer that translates old-format data to
  new-format before it reaches the new reader.

## Data compatibility

### Dual-write patterns

Both old and new stores receive writes during the transition.

**Patterns:**
- **Synchronous dual-write:** Write to both stores in the same transaction or
  unit of work. Strong consistency; adds latency and a failure mode (what if one
  write succeeds and the other fails?).
- **Asynchronous dual-write:** Write to the primary store, then publish an event
  that the secondary store consumes. Eventual consistency; the secondary store
  lags behind the primary. Acceptable when the lag is bounded and monitored.
- **Change-data-capture (CDC):** The secondary store tails the primary's write-
  ahead log or change stream. No application code change; the CDC pipeline must
  be monitored for lag and errors.

### Dual-read patterns

Both old and new stores are read during the transition for comparison.

**Patterns:**
- **Shadow read:** Read from the new store in parallel with the old store;
  compare results; use the old store's result for the response. Log mismatches.
- **Percentage read:** Route a configurable percentage of reads to the new
  store. Increase over time as confidence grows.
- **Consumer-driven read:** Individual consumers opt into reading from the new
  store. Track per-consumer migration status.

## API compatibility

### Additive changes (safe)

- Adding a new endpoint or field.
- Adding an optional query parameter.
- Adding a new enum value (if consumers handle unknown values gracefully).
- Adding a new response header.

### Breaking changes (require compatibility window)

- Removing an endpoint, field, or enum value.
- Renaming a field or endpoint.
- Changing a field type or response shape.
- Changing authentication requirements.
- Changing error response format.
- Changing rate limits downward.

For breaking changes, use the expand/contract pattern: add the new interface
alongside the old, give consumers a migration window, track consumer migration,
then remove the old interface.

## Infrastructure compatibility

### Network continuity

- DNS migration: lower TTL before the change, dual-publish old and new records
  during the transition, verify propagation before removing old records.
- Certificate rotation: deploy new certificates before old ones expire; both
  old and new certificates must be valid during the overlap window.
- Service discovery: register the new service instance before deregistering the
  old one.

### Data-plane continuity

- Database connection strings: dual-configure applications with both old and new
  connection parameters; switch via configuration, not code deploy.
- Message broker migration: dual-publish to old and new brokers; dual-consume
  during the transition; verify no message loss before shutting down the old
  broker.

# 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](../api-design-and-evolution/SKILL.md).
   Migration engineering cites the API compatibility policy; it does not define it.
2. **Database DDL, ETL pipeline implementation, backfill script authoring** →
   [data-engineering](../data-engineering/SKILL.md). Migration engineering
   defines the backfill strategy; data engineering implements it.
3. **Infrastructure provisioning, Terraform modules, Helm charts** →
   [platform-engineering](../platform-engineering/SKILL.md). Migration
   engineering defines the staging sequence; platform engineering provisions it.
4. **Release pipeline mechanics, canary configuration, feature flag implementation** →
   [release-engineering](../release-engineering/SKILL.md). Migration engineering
   defines the migration gates; release engineering implements the promotion pipeline.
5. **SLO definition, error budget policy, incident response procedure** →
   [site-reliability-engineering](../site-reliability-engineering/SKILL.md).
   Migration engineering consumes the error budget as a gate; SRE defines it.
6. **Work breakdown, dependency mapping, critical path, ownership assignment** →
   [implementation-planning](../implementation-planning/SKILL.md). 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](../secure-software-engineering/SKILL.md).
8. **Retirement decision and customer communication** →
   [product-lifecycle-learning](../product-lifecycle-learning/SKILL.md). Migration
   engineering executes the technical side of a retirement-triggered migration.
9. **Test strategy and verification gate design** →
   [qa-methodology](../qa-methodology/SKILL.md) and
   [verification-methodology](../verification-methodology/SKILL.md).

# Migration Types

Load this file when classifying a migration before selecting patterns: each
type has materially different compatibility, correctness, and recovery
characteristics, and real-world migrations often combine types (a service
extraction is usually a combined infrastructure/service, API, and data
migration).

## Schema migration

A change to a database schema, message format, or serialization contract.
**Compatibility:** forward compatibility (old readers tolerate new writers) and
backward compatibility (new readers tolerate old writers) are the central design
constraints. **Correctness:** verified by dual-reading or shadow-traffic
comparison — the new schema must produce equivalent results for the same input.
**Rollback:** possible if the schema change is purely additive (expand phase);
destructive changes (drop column, rename, change type) require a multi-step
expand/contract sequence with a compatibility window where both old and new
schemas coexist before the old is removed.

## Data migration

Movement or transformation of data between stores, representations, or
ownership boundaries. **Compatibility:** the old and new data representations
must coexist during the transition; consumers may read from either or both.
The backfill strategy (full, incremental, or streaming) determines how long
the dual-read window lasts. **Correctness:** requires reconciliation — a
record-level or aggregate comparison between source and target to verify
completeness and accuracy before cutover. **Rollback:** depends on whether the
old store remains writable and current during the transition. If the old store
is kept in sync (dual-write), rollback is reversing the cutover. If the old
store was dropped or made read-only, rollback requires restore from backup.

## API migration

A change to the contract between a provider and its consumers — versioning,
protocol, schema, or endpoint topology. **Compatibility:** defined by the
provider's compatibility policy (e.g., "additive changes are backward-compatible;
removals require a deprecation window"). The compatibility window is measured
in consumer migration time — how long consumers need to move from the old
interface to the new one. **Correctness:** verified by consumer-side testing,
shadow-traffic replay, and error-rate comparison between old and new interfaces.
**Rollback:** the old interface must remain available and supported throughout
the deprecation window; rolling back means reverting the deprecation notice
and keeping the old interface live. Once the old interface is removed, rollback
requires deploying it again — a restore or redeploy path, not a simple reversal.

## Infrastructure and service migration

Moving workloads, services, or infrastructure between environments, platforms,
or ownership domains. **Compatibility:** network, identity, and data-plane
continuity must be maintained. DNS, certificates, service discovery, and
security boundaries are the primary compatibility surface. **Correctness:**
verified by traffic shifting, canary deployment, and service-level objective
(SLO) monitoring during the transition. **Rollback:** depends on the migration
topology. Lift-and-shift with the old environment preserved is reversible;
in-place replacement without a preserved old environment may be irreversible
or require a full redeploy (roll-forward/restore).

## Service extraction

A service extraction is usually a combined infrastructure/service, API, and data
migration. Before the expand phase, record the proposed capability's boundary
evidence, coupling, data ownership, callers, and failure behavior. Select the
least disruptive transition pattern that creates evidence: strangler routing,
branch by abstraction, an anti-corruption boundary, CDC, parallel run, or a
combination with distinct roles. Keep the old path selectable until comparison,
reconciliation, customer-impact, and operational gates pass.

The extraction assessment must also record explicit reasons to retain a modular
monolith. If the boundary still needs shared writes, frequent cross-boundary
transactions, unobservable consumers, or has no tested recovery path, stop and
recommend modular improvement or request more evidence rather than creating a
distributed shape by default. Route target-boundary justification to the
[`software-architecture`](../software-architecture/SKILL.md) decision owner;
migration-engineering owns the safe current-to-target transition once authorized.

For transition-pattern selection detail, load
[`service-extraction-patterns.md`](service-extraction-patterns.md).

# Structured Planning Fields

Load this file when drafting or reviewing a migration plan: every plan must
address these fields. They may appear as checklist items, template fields,
table columns, or labeled section headers — not only as prose. The
[`../templates/migration-plan.md`](../templates/migration-plan.md) template
provides the ready-made structure that instantiates these fields.

## Reconciliation

| Field | Question to answer |
|---|---|
| Strategy | Full, incremental, or streaming reconciliation? |
| Frequency | Continuous, hourly, daily, or pre-cutover only? |
| Coverage | All records or a statistical sample? |
| Tolerance | What divergence is acceptable? |
| Failure action | Stop, alert, or automatically re-reconcile? |

## Correctness evidence

| Field | Question to answer |
|---|---|
| Comparison method | Dual-read, shadow-traffic, consumer-side test, or synthetic validation? |
| Pass criteria | What measurements confirm correctness (e.g., "100% record match," "error rate < 0.01%," "p95 latency within 10% of baseline")? |
| Evidence artifact | Where is the evidence recorded (dashboard link, test report, reconciliation log)? |

## Observability

| Field | Question to answer |
|---|---|
| Progress metrics | Bytes migrated, records processed, consumers cut over? |
| Anomaly signals | Error-rate spikes, latency degradation, reconciliation drift? |
| Dashboards and alerts | Where are migration-specific metrics visible, and who is on-call? |

## Customer impact

| Field | Question to answer |
|---|---|
| Visible change | What does the customer experience during each phase? |
| Downtime | Is any downtime expected, and how is it communicated? |
| Performance | Could latency, throughput, or error rates change during the migration? |
| Support | How are customer issues triaged and escalated during the migration window? |

## Ownership

| Field | Question to answer |
|---|---|
| Migration lead | Who owns the overall migration plan and its execution? |
| Phase owners | Who is accountable for expand, dual-running, cutover, deprecation, and cleanup? |
| Communication owner | Who owns stakeholder and consumer notifications? |
| Escalation path | Who is the decision-maker if the migration must be paused, rolled back, or abandoned? |

# Recovery Classification

Deep reference on the four recovery paths with decision rules, examples, and
anti-patterns. Load this reference when classifying recovery for concrete
migration steps.

## The four recovery paths

### Rollback

Reverse to the prior state by undoing the change.

**Decision rule:** Rollback is possible when the old state still exists and can
be reactivated, OR the change is purely additive and can be removed without side
effects.

**Examples:**
- Undo a feature-flag-controlled code path by turning off the flag.
- Restore read traffic to the old database by reverting the connection string.
- Drop a newly added nullable column that is not yet consumed.
- Cancel a deprecation notice and keep the old API endpoint live.

**Anti-patterns:**
- Claiming rollback is possible because "we can fix it in the next deploy."
  That is roll-forward, not rollback.
- Claiming rollback is possible when the old system has been decommissioned.
  That is restore or irreversible.

### Roll-forward

Fix forward in the new state. The old state is no longer reachable, but a fix
can be deployed to the new system.

**Decision rule:** Roll-forward is the correct path when (a) reversal is
impossible or more expensive than fixing forward, AND (b) a fix can be deployed
within the acceptable recovery window.

**Examples:**
- A data migration cutover has completed and the old store is read-only; a bug
  in the new service is discovered. Deploy a fix to the new service.
- An API migration has removed the old endpoint; a consumer reports a
  regression. Fix the new endpoint.
- A configuration error in the new infrastructure is causing errors. Correct
  the configuration and redeploy.

**Anti-patterns:**
- Using roll-forward as the default recovery path without assessing whether
  rollback is simpler and safer.
- Failing to define the acceptable fix-forward window (how long can the system
  be degraded before the fix lands?).

### Restore

Restore the prior state from a backup or snapshot.

**Decision rule:** Restore is the path when the old system is no longer
operational but a backup exists and a restore procedure is tested and has a
known recovery time.

**Examples:**
- A schema migration dropped the wrong table; restore from the pre-migration
  backup.
- A data migration corrupted the target store; restore the target from the
  pre-migration snapshot and re-run the migration.
- An infrastructure migration destroyed the old environment; restore from the
  infrastructure-as-code state and redeploy.

**Anti-patterns:**
- Assuming restore is possible because "we have backups." A backup that has not
  been tested with a restore drill is not a recovery path — it is a hope.
- Failing to define the Recovery Time Objective (RTO) and Recovery Point
  Objective (RPO) for the restore.

### Irreversible

Reversal is impossible. The change cannot be undone at any level.

**Decision rule:** Irreversible when (a) the old state is physically destroyed,
(b) the operation is one-way by design (e.g., cryptographic erasure), or (c) a
third-party action cannot be recalled.

**Examples:**
- Physical hardware decommissioning where the device is shipped back and
  wiped.
- Cryptographic key rotation where old keys are destroyed after rotation.
- Third-party data export where the receiving party cannot be compelled to
  delete the data.
- Permanent data deletion to satisfy a regulatory requirement (e.g., GDPR
  right-to-erasure).

**Required for every irreversible step:**
1. **Acceptance criteria** — what conditions must be met before the
   irreversible step is executed (e.g., "reconciliation passed at 100% for 7
   consecutive days").
2. **Stakeholder communication** — who must be informed and who must approve
   before the step executes.
3. **Contingency plan** — what happens if the irreversible step succeeds but
   the overall migration subsequently fails (e.g., "rebuild from source of
   truth," "accept data loss within defined scope").

**Anti-patterns:**
- Treating an irreversible step as if it were reversible — stating "rollback:
  N/A" without the acceptance, communication, and contingency requirements.
- Claiming "irreversible" for a step that is merely expensive or inconvenient to
  reverse. Irreversible means physically or logically impossible, not merely
  costly.

## Classification decision tree

```
Can the old state be reactivated without data loss?
  ├── YES → Rollback is possible
  └── NO:
      ├── Can the new state be fixed within the acceptable recovery window?
      │   └── YES → Roll-forward is possible
      └── Can the old state be restored from backup?
          ├── YES, and restore procedure is tested → Restore is possible
          └── NO → Irreversible
```

## When not to claim rollback

Never claim rollback is possible when:
- The old system has been decommissioned and cannot be restarted.
- The old data has been deleted and no backup exists.
- The old API has been removed and cannot be redeployed.
- A third-party action cannot be reversed.
- The rollback procedure has never been tested.

In these cases, classify as roll-forward, restore, or irreversible — not as
rollback with caveats.

# Service Extraction Patterns

Load this reference when a migration moves a capability out of a modular or
distributed monolith into an independently deployed service. It helps choose a
transition shape after the candidate boundary has been identified; it does not
decide whether the organization should decompose the system.

## Boundary evidence before sequencing

Treat a proposed extraction seam as a hypothesis. Record evidence for the
capability, not enthusiasm for a deployment style:

- **Capability coherence:** the behavior has a recognizable business purpose,
  stable language, and a bounded set of invariants.
- **Data ownership:** the candidate can name the records it owns, the writers,
  the authoritative source, retention rules, and the queries that must cross
  the proposed boundary.
- **Change seam:** the capability changes, scales, is secured, or is released
  on a different cadence from its neighbors. A high edit count alone is not
  sufficient; show who changes what and which releases are coupled.
- **Coupling shape:** map synchronous calls, shared tables, foreign keys,
  transactions, events, batch jobs, caches, feature flags, and operational
  dependencies. Include temporal coupling such as required ordering and
  deployment coupling such as coordinated releases.
- **Consumer surface:** identify callers, data consumers, operators, external
  partners, and customer-visible workflows. A seam with one clear owner is
  easier to transition than one with many unowned consumers.
- **Failure boundary:** state which failures may be isolated and which business
  invariants currently depend on one local transaction.

If the evidence cannot identify a data owner, a stable contract, or a bounded
failure behavior, stop at discovery. Do not manufacture a service boundary to
make the plan look complete. Route the decomposition decision and target
boundary to the repository's software-architecture owner when that skill is
available; this skill begins once a current-to-target transition is authorized.

## Pattern selection

Choose one primary transition pattern and name any supporting pattern. The
default is the least disruptive shape that creates useful evidence.

| Pattern | Use when | Main evidence | Main risk | Reversal posture |
|---|---|---|---|---|
| **Strangler routing** | A request path can move endpoint-by-endpoint or capability-by-capability | Traffic and outcome comparisons by route and consumer | Hidden callers bypass the route or semantics differ | Usually strong while the old path remains live |
| **Branch by abstraction** | Callers can be placed behind a stable internal interface before the implementation moves | Contract tests and parity checks at the abstraction | The abstraction becomes a new leaky coupling layer | Strong while the old implementation remains selectable |
| **Anti-corruption boundary** | The new service needs a different model or vocabulary from the monolith | Explicit translation rules, ownership, and rejected legacy concepts | Translation hides unresolved ownership or loses meaning | Good if translation is isolated and old model remains available |
| **Change-data capture (CDC)** | The source database remains authoritative while a target is populated or kept current | CDC lag, ordering, replay, dead-letter handling, and reconciliation | Missed changes, schema drift, duplicate delivery, and unclear deletes | Good before source write ownership changes; weaker after contract |
| **Parallel run** | Both implementations can process the same inputs safely for comparison | Deterministic comparison, side-effect isolation, and mismatch triage | Duplicate side effects, non-determinism, and double cost | Strong only when the old result remains authoritative |

Do not present these as interchangeable synonyms. Routing changes where a
request is handled; abstraction changes which implementation callers invoke;
translation protects a model boundary; CDC moves changes; parallel run creates
comparison evidence. A plan may combine them, but should state the role of each.

## Sequencing a service extraction

Use the existing migration lifecycle and fill it with extraction-specific
decisions:

1. **Prove the seam.** Inventory callers, writes, reads, transactions, jobs,
   and customer journeys. Identify the source of truth and the invariant that
   must not be split accidentally.
2. **Make the old path selectable.** Add routing, an abstraction, or an
   adapter without changing the old behavior. Define the feature-flag or
   configuration owner and the interruption point.
3. **Establish the target contract.** Add the service interface and translate
   legacy concepts at the boundary. Route contract semantics and versioning to
   `api-design-and-evolution`; do not hide breaking changes in an adapter.
4. **Populate and synchronize data.** Choose full, incremental, or streaming
   backfill. If CDC or events are used, specify ordering, duplicates, deletes,
   replay, lag limits, schema compatibility, and dead-letter recovery. Route
   pipeline implementation to `data-engineering`.
5. **Compare before authority moves.** Use shadow reads or parallel execution
   with side effects disabled, or compare independently observable outcomes.
   Define mismatch categories and a stop rule before collecting results.
6. **Shift traffic or callers in bounded increments.** Every increment needs a
   precondition, customer-impact check, abort trigger, and recovery
   classification. Route rollout mechanics to `release-engineering` and SLO
   gates to `site-reliability-engineering`.
7. **Transfer ownership explicitly.** Declare when the target becomes the
   source of truth, which writers are disabled, and how stale old data is
   handled. Do not call a read switch an ownership transfer unless writes and
   reconciliation support that claim.
8. **Contract only after evidence.** Remove old routes, adapters, shared-table
   access, CDC feeds, flags, and credentials only after the compatibility and
   deprecation conditions pass. Classify each removal separately; expensive is
   not the same as irreversible.

## Coupling and data ownership checks

Before selecting CDC or dual-write, answer these questions:

- Is there one authoritative writer, or would two systems claim ownership?
- Can the invariant be enforced without a distributed transaction?
- Are updates, deletes, retries, and out-of-order changes represented?
- Can a CDC consumer replay from a known position and reconcile the result?
- Are reads allowed to observe bounded staleness, and who accepts it?
- Which queries currently join the candidate data with data outside the seam?
- What happens when the target is unavailable: queue, reject, serve old data,
  or degrade with a stated customer impact?
- Which old writes remain possible after target cutover, and how are they
  detected?

If the answers require frequent cross-boundary transactions, synchronous calls
in both directions, or shared writes with no clear authority, prefer a modular
monolith increment or branch-by-abstraction experiment. A distributed shape
that preserves the old coupling has added failure modes without buying an
independent boundary.

## Coexistence and reversibility record

For each phase, record:

| Concern | Required decision |
|---|---|
| Coexistence | Which old and new routes, readers, writers, schemas, and data stores are live together? |
| Authority | Which system is authoritative for each operation and data field? |
| Comparison | What is compared, with what tolerance, and what stops promotion? |
| Customer impact | What can users observe in latency, ordering, availability, or semantics? |
| Recovery | Is the step rollback, roll-forward, restore, or irreversible, and what is the tested procedure? |
| Exit condition | What metric, consumer state, or owner decision permits the next phase? |
| Cleanup | Which old dependency is removed, and is its removal reversible? |

Rollback is normally available while the old implementation remains
authoritative or selectable. Once writes are exclusive to the new store, the
old store is deleted, or the old contract cannot be redeployed, do not promise
rollback. Use roll-forward, restore, or irreversible classification as defined
in `references/recovery-classification.md`.

## When to keep a modular monolith

Recommend retaining or strengthening the modular monolith when evidence shows
that extraction would not create a meaningful boundary. Explicit reasons may
include:

- the capability shares invariants that need one local transaction;
- data ownership is contested or the proposed service would still share tables;
- callers are numerous, implicit, or not observable enough to migrate safely;
- the target would require synchronous calls in both directions for normal work;
- the expected scale, release cadence, security isolation, or team ownership
  difference is not material;
- the operation cannot tolerate the latency, partial failure, or eventual
  consistency introduced by the boundary;
- the migration has no tested recovery path within the accepted impact;
- the modular monolith can address the stated problem with module boundaries,
  dependency rules, an internal abstraction, or isolated runtime resources.

"Keep the monolith" is not a failure to decide. Record the evidence, the
modular improvement to make, the condition that would reopen extraction, and
the owner/date for reassessment. If the decision is unresolved, stop before
service creation and escalate rather than selecting a pattern by default.

## Specialist boundaries

- Target-boundary justification and architecture decomposition belong to
  [`software-architecture`](../../software-architecture/SKILL.md); this reference
  sequences an approved transition.
- API contract semantics and compatibility policy belong to
  `api-design-and-evolution`.
- CDC, backfill, schemas, and reconciliation implementation belong to
  `data-engineering`.
- Routing implementation, feature flags, and traffic promotion belong to
  `release-engineering` and `platform-engineering`.
- SLOs, error budgets, alerts, and incident response belong to
  `site-reliability-engineering`.
- Security boundary and authorization review belong to
  `secure-software-engineering`.

# Compatibility Matrix Template

Build a compatibility matrix for a multi-consumer migration. Each row is a
consumer or dependency; each column is a migration phase.

## Matrix

| Consumer / Dependency | Current interface | Expand compatible? | Compatibility window status | Cutover ready? | Contract safe? | Notes |
|---|---|---|---|---|---|---|
| | | | | | | |
| | | | | | | |
| | | | | | | |

## Column definitions

- **Consumer / Dependency:** The system, service, team, or external partner
  that depends on the interface being migrated.
- **Current interface:** What the consumer uses today (e.g., "REST v1
  /orders", "Postgres orders table", "us-east-1 ECS cluster").
- **Expand compatible?:** Can this consumer continue to operate when the new
  interface is added alongside the old? "Yes" means no action required from
  the consumer during the expand phase. "No" means the consumer must take
  action before or during expand.
- **Compatibility window status:** The consumer's progress toward migrating to
  the new interface. Values: "Not started", "In progress (N% complete)",
  "Migrated — monitoring", "Migrated — verified".
- **Cutover ready?:** Has this consumer verified that it works correctly with
  the new interface and is prepared for the old interface to be removed?
- **Contract safe?:** Can the old interface be removed without breaking this
  consumer? Must be "Yes" for all consumers before the contract phase.
- **Notes:** Contact person, migration deadline, special requirements, or
  known issues.

## Consumer communication log

| Date | Consumer | Message | Response |
|---|---|---|---|
| | | | |

# Cutover and Recovery Record Template

Record the cutover procedure, recovery paths per step, and irreversible-step
acknowledgments for a migration.

## Cutover sequence

| Step # | Action | Performed by | Pre-condition | Expected result | Actual result | Interruption possible? | Rollback action |
|---|---|---|---|---|---|---|---|
| 1 | | | | | | | |
| 2 | | | | | | | |
| ... | | | | | | | |

## Cutover gate checklist

- [ ] Reconciliation passed for all data domains (see reconciliation plan).
- [ ] All consumers confirmed ready (see compatibility matrix).
- [ ] Observability dashboards deployed and verified.
- [ ] On-call responder briefed on cutover procedure and abort triggers.
- [ ] Rollback procedure tested (where applicable).
- [ ] Irreversible steps acknowledged (see below).
- [ ] Communication sent to stakeholders and consumers.

## Abort triggers

| Trigger | Threshold | Action |
|---|---|---|
| Error rate exceeds | | |
| Latency exceeds | | |
| Reconciliation drift detected | | |
| Consumer-reported issue | | |

## Recovery classification per step

| Step | Classification | Procedure | RTO | Tested date |
|---|---|---|---|---|
| | Rollback / Roll-forward / Restore / Irreversible | | | |

## Irreversible step acknowledgment

For each step classified as **Irreversible**:

### Step: [step description]

| Field | Value |
|---|---|
| Why is this step irreversible? | |
| Acceptance criteria that must be met before execution | |
| Stakeholders notified | |
| Stakeholder approval obtained from | |
| Contingency plan if migration fails after this step | |

### Sign-off

| Name | Role | Date | Signature |
|---|---|---|---|
| | Migration lead | | |
| | Stakeholder | | |

## Cutover execution log

| Timestamp | Step | Performed by | Result | Notes |
|---|---|---|---|---|
| | | | | |

# Migration Plan Template

Fill this template for every migration that crosses a system boundary.

## Migration identity

| Field | Value |
|---|---|
| Migration name | |
| Migration type(s) | Schema / Data / API / Infrastructure-Service |
| Current state | |
| Target state | |
| System boundary | |
| Risk class | Low / Medium / High |

## Expand/Contract sequence

| Phase | Description | Duration | Gate |
|---|---|---|---|
| Expand | | | |
| Compatibility window | | | |
| Dual-running (if applicable) | | | |
| Contract | | | |

## Backfill strategy (data migrations)

| Field | Value |
|---|---|
| Strategy | Full / Incremental / Streaming |
| Estimated volume | |
| Estimated duration | |
| Pre-conditions | |

## Reconciliation

| Field | Value |
|---|---|
| Strategy | Full / Incremental / Streaming |
| Frequency | Continuous / Hourly / Daily / Pre-cutover only |
| Coverage | All records / Statistical sample (size: ___) |
| Tolerance | |
| Failure action | Stop / Alert / Auto-reconcile |

## Cutover procedure

| Step | Action | Pre-condition | Post-condition | Interruption point? |
|---|---|---|---|---|
| 1 | | | | |
| 2 | | | | |
| ... | | | | |

| Field | Value |
|---|---|
| Cutover window duration | |
| Acceptable downtime | |
| Abort trigger | |

## Recovery paths

| Migration step | Recovery classification | Procedure | RTO | Tested? |
|---|---|---|---|---|
| | | | | |
| | | | | |

### Irreversible steps

| Step | Acceptance criteria | Stakeholder sign-off required | Contingency plan |
|---|---|---|---|
| | | | |

## Correctness evidence

| Field | Value |
|---|---|
| Comparison method | Dual-read / Shadow-traffic / Consumer-side test / Synthetic validation |
| Pass criteria | |
| Evidence artifact | |

## Observability

| Field | Value |
|---|---|
| Progress metrics | |
| Anomaly signals | |
| Dashboards and alerts | |
| On-call rotation | |

## Customer impact

| Phase | Visible change | Downtime | Performance impact | Communication |
|---|---|---|---|---|
| Expand | | | | |
| Compatibility window | | | | |
| Cutover | | | | |
| Contract | | | | |

## Ownership

| Role | Name / Team | Accountable for |
|---|---|---|
| Migration lead | | Overall plan and execution |
| Expand phase owner | | |
| Dual-running phase owner | | |
| Cutover phase owner | | |
| Deprecation phase owner | | |
| Communication owner | | Stakeholder and consumer notifications |
| Escalation decision-maker | | Pause, rollback, or abandon decisions |

## Deprecation and cleanup

| Activity | Target date | Owner | Dependencies |
|---|---|---|---|
| Deprecation announcement | | | |
| Consumer migration deadline | | | |
| Old system read-only | | | |
| Old system removal | | | |
| Code/flag cleanup | | | |
| Credential revocation | | | |

## Sign-off

| Role | Name | Date | Signature |
|---|---|---|---|
| Migration lead | | | |
| (Irreversible steps only) Stakeholder | | | |

# Reconciliation Plan Template

Design a reconciliation strategy for a data migration. Fill one template per
data source/target pair.

## Data scope

| Field | Value |
|---|---|
| Source system | |
| Target system | |
| Data domain (tables, collections, keyspaces) | |
| Estimated record count | |
| Primary key or natural key | |

## Reconciliation dimensions

### Completeness

| Field | Value |
|---|---|
| Method | Row count comparison / Key-space scan / Checksum comparison |
| Frequency | |
| Pass threshold | (e.g., "exact match", "within 0.01%") |

### Accuracy

| Field | Value |
|---|---|
| Method | Field-level comparison / Hash comparison / Sample verification |
| Sample size (if sampled) | |
| Fields compared | |
| Tolerance per field | (e.g., "amount: within 0.01", "timestamp: within 1s") |
| Frequency | |

### Timeliness

| Field | Value |
|---|---|
| Lag tolerance | (e.g., "target within 5 seconds of source") |
| Measurement method | |
| Frequency | |

### Consistency

| Field | Value |
|---|---|
| Related-record checks | (e.g., "every order has matching line items") |
| Referential-integrity checks | |
| Frequency | |

## Reconciliation failure protocol

| Condition | Action |
|---|---|
| Completeness check fails | |
| Accuracy check fails | |
| Timeliness check fails | |
| Consistency check fails | |

## Reconciliation run log

| Run timestamp | Completeness result | Accuracy result | Timeliness result | Consistency result | Overall | Action taken |
|---|---|---|---|---|---|---|
| | | | | | | |

# Service Extraction Assessment Template

Use this assessment after a service-extraction target has been proposed and
before sequencing the migration. It records evidence and preserves a modular
monolith as an explicit outcome. It does not replace the architecture decision
that authorizes or rejects decomposition.

## Decision frame

| Field | Value |
|---|---|
| Assessment name | |
| Decision owner | |
| Current system and modules | |
| Proposed capability | |
| Proposed target boundary | |
| Business or operational problem to solve | |
| Evidence window and sources | |
| Decision status | Extract / Keep modular monolith / More evidence required |

## Boundary evidence

| Evidence area | Observed evidence | Confidence / gap | Owner |
|---|---|---|---|
| Capability purpose and language | | | |
| Invariants and transaction scope | | | |
| Data owned and authoritative writers | | | |
| Inbound callers and consumers | | | |
| Outbound dependencies | | | |
| Static and dynamic coupling | | | |
| Change and deployment coupling | | | |
| Failure and recovery boundary | | | |
| Customer journeys and impact | | | |
| Team and operational ownership | | | |

## Coupling and data ownership

| Question | Answer / evidence |
|---|---|
| Which records and fields would the target own? | |
| Which system is authoritative before, during, and after cutover? | |
| Which writes cross the proposed boundary? | |
| Which reads require joins or synchronous calls across it? | |
| Which invariants currently rely on a local transaction? | |
| Are deletes, retries, ordering, and replay defined? | |
| Is eventual consistency acceptable? For which user-visible actions? | |
| What happens when the target is unavailable? | |
| What hidden callers, jobs, reports, or caches may bypass the intended path? | |
| What evidence would disprove the proposed boundary? | |

## Pattern selection

| Candidate pattern | Role in this transition | Why it fits / does not fit | Evidence required |
|---|---|---|---|
| Strangler routing | | | |
| Branch by abstraction | | | |
| Anti-corruption boundary | | | |
| Change-data capture (CDC) | | | |
| Parallel run | | | |

**Selected primary pattern:**

**Supporting patterns:**

**Rejected pattern and reason:**

## Coexistence and migration sequence

| Phase | Old path live? | New path live? | Read authority | Write authority | Comparison / gate | Customer impact |
|---|---|---|---|---|---|---|
| Expand | | | | | | |
| Backfill / synchronization | | | | | | |
| Shadow or parallel run | | | | | | |
| Traffic or caller shift | | | | | | |
| Ownership transfer | | | | | | |
| Deprecation | | | | | | |
| Contract / cleanup | | | | | | |

## Data movement and correctness

| Field | Decision |
|---|---|
| Backfill mode | Full / Incremental / Streaming / Not applicable |
| CDC or event source | |
| Ordering and duplicate handling | |
| Delete propagation | |
| Replay and dead-letter recovery | |
| Reconciliation dimensions | Completeness / Accuracy / Timeliness / Consistency |
| Comparison method | Dual-read / Shadow execution / Consumer test / Synthetic validation |
| Pass threshold and observation period | |
| Hard stop condition | |
| Evidence artifact and owner | |

## Reversibility and operational risk

| Step or state | Recovery classification | Trigger to stop or abort | Tested procedure / gap | RTO / RPO |
|---|---|---|---|---|
| Routing or abstraction enabled | Rollback / Roll-forward / Restore / Irreversible | | | |
| Target deployed | Rollback / Roll-forward / Restore / Irreversible | | | |
| Data synchronized | Rollback / Roll-forward / Restore / Irreversible | | | |
| Read authority shifted | Rollback / Roll-forward / Restore / Irreversible | | | |
| Write authority transferred | Rollback / Roll-forward / Restore / Irreversible | | | |
| Old data or code removed | Rollback / Roll-forward / Restore / Irreversible | | | |

| Operational risk | Likelihood / impact | Mitigation and evidence | Accountable owner |
|---|---|---|---|
| Latency or throughput regression | | | |
| Partial failure or dependency outage | | | |
| Data divergence or lost change | | | |
| Duplicate or reordered side effect | | | |
| Security or authorization drift | | | |
| Observability and support gap | | | |
| On-call and ownership load | | | |
| Customer-visible semantic change | | | |

## Reasons to keep a modular monolith

Complete this section even when extraction is recommended. Mark each reason as
observed, plausible, or not applicable, and cite evidence.

| Retention reason | Status | Evidence / counter-evidence | Modular improvement or follow-up |
|---|---|---|---|
| Shared invariants require one local transaction | | | |
| Data ownership is unclear or remains shared | | | |
| Coupling would move rather than decrease | | | |
| Consumers or operational dependencies are not observable | | | |
| Distributed latency, failure, or consistency is unacceptable | | | |
| Scale, release cadence, isolation, or team ownership does not justify a service | | | |
| No tested recovery path fits the accepted impact | | | |
| Modules, dependency rules, or internal abstractions solve the stated problem | | | |

**Decision to retain the modular monolith, if applicable:**

**Condition that would reopen extraction:**

**Reassessment owner and date:**

## Handoff and approval

| Role | Name / team | Decision or implementation responsibility |
|---|---|---|
| Architecture decision owner | | Boundary and decomposition justification |
| Migration lead | | Current-to-target transition |
| API owner | | Contract and consumer compatibility |
| Data owner | | Backfill, CDC, and reconciliation implementation |
| Platform / release owner | | Runtime, routing, flags, and promotion |
| SRE / operations owner | | SLO gates, alerts, and response readiness |
| Security owner | | Trust boundary and authorization review |

**Approval or escalation record:**