Migration Strategy
When to use
- The transformation is too broad, too split into parts, too heavy in what it must preserve, or too risky operationally for ordinary feature planning and line-by-line review.
- Classify the change before implementing anything, from evidence of risk,
not from the line count. Answer four questions: can independent people or
checks inspect the result (reviewability); must behavior,
compatibility, data, or operations match (preservation); how many
owners, consumers, platforms, or modes change (breadth); can data,
security, concurrency, resources, cutover, or recovery each fail on its own
(failure surfaces)? If the ordinary route cannot make those surfaces
reviewable and recoverable, hold work on the target until this contract
is approved and
verification-strategy's entry gates have passed. If the answers are uncertain, recordpending classificationin theRoutefield of the spec, design section, or plan index that carries the change. Classify it again whenever the inputs change. Until it is resolved, only work that settles those answers proceeds: nothing on the target changes. - Skip a bounded change whose behavior and diff can still be reviewed directly; such work stays on its ordinary route.
- Write the facts about the source and the strategy for the transition here.
Send the shape of the target to
system-architecture, the proof toverification-strategy, and the tasks towriting-plans.
Step 1: Establish the ground truth
Open assets/migration-contract.md before the steps below; each step fills
the section of it that the step names.
- Fill
Normative control: the source and target revisions, the scope, and one accountable owner or an approval rule. If the target is not settled, go back tosystem-architecturefirst. - Fill
Source-fact inventoryas the template lists. Name each place searched for consumers; each one not searched (direct database readers, scheduled jobs, exports, other repositories) is anUnknown contractrow. - Classify every fact, in
Preservation and deviation contractor inUnknown contract, as one of: a preserved invariant, an intentional deviation, or an unknown. - For each deviation, attach the approved requirement or decision that owns it. A newly discovered choice goes back to that owner; never settle it here.
- Each unknown blocks until it is proved irrelevant or approved with a compensating gate.
Step 2: Design the transition
- Fill
Transition and translationas the template lists. - Fill
Representative trial sliceas the template lists. - Fill
Partitions and ownership: a stable inventory of shards and the rules for who owns each. Attempts, owners, heartbeats, transfers, and results go into a ledger (a record kept outside the contract: add to it, never rewrite it), never into the contract.
Step 3: Control what moves underneath you
- Fill
Source evolution during migration: either freeze the source, or run one versioned change-intake contract and an external queue. Every source change after the baseline gets an identity and an exact terminal disposition, with its evidence. - Fill
Mutable live-state catch-upwherever data or work keeps moving: from how the boundary is bound through to the maximum permitted lag and the gate that owns that limit. Every write after the snapshot lands in exactly one terminal disposition, with its evidence. "Probably applied" is not reconciled and blocks cutover. - Fill
Convergence and failure queue: reconcile the external ledgers, and give every skip an approved recorded decision. If one class of failure repeats, pause the affected work, fix the shared rule, and re-audit every impacted shard. - Fill
Pause, abort, cutover, and rollback,Retained artifacts, andDecommission and retained-source retirementbefore anyone needs them. In the rollback rule, say what happens to each write the target accepted after cutover: replayed to the source, or a loss its owner approved. - Enter decommission only when the retention period has elapsed, live use is provably zero, its gate has passed, and its targets, authority, and recovery are written down. A decommission action that is partial, failed, or failed its validation blocks release and cleanup.
Step 4: Write, challenge, then decide
Write the contract to
.sdlc-skills/designs/{{YYYY-MM-DD}}-{{topic}}-migration.md. Keep the review state, the decision state, and the execution state outside it. Compute its identity now, as the template says; the challengers bind to this path and this identity.Fill
assets/migration-challenger.mdwith that path and identity before approval, then dispatch two read-only challengers asdispatching-parallel-agentsStep 2 says, bound to the contract'sIndependent challenge contract: one who knows the source and its domain, and one who owns operations and data.For any role left out, record an accountable skip; the template's
Independent challenge coveragefield says what one carries. Bind each challenge to one exact attempt with a deadline. A required role blocks approval until its current report on this contract identity readsclear.revisetakes one successor contract and one re-challenge by that role;inconclusive, the missing input and one rerun. If a role is still notclear, report its open findings to theApproval ruleowner and end the turn. The owner accepts a finding only by naming it: recordaccepted by {{owner}}with the finding in the ledger, and present the contract once every open finding is accepted or corrected. A reply that names none accepts none.Present the contract:
Migration contract {{path}} version {{identity (per template)}} — {{strategy}} Preserves: {{invariants}}. Trial: {{slice}}. Pause/abort/rollback: {{rules}}. Retirement: {{plan}}. 1. Approve this exact version for planning 2. Request changes 3. Reject the strategy 4. Cancel Recommendation: {{option}} — {{one sentence}}.Ask this and end the turn;
clarifying-intentowns what closes it.Only an approved exact version, with the consumers bound to its predecessor reconciled, proceeds. REQUIRED SUB-SKILL: invoke
verification-strategywhen this version's entry gates are missing; otherwise invokewriting-plans.
Gotchas
- Code review judges the exact version under review against an approved contract. Before approval neither exists, so a challenge sent to code review has nothing to bind to and returns no verdict.
- The trial slice's coverage inventory (Step 2) is only as stable as the source is frozen or its changes are taken in under control (Step 3). A new consumer, platform, or path that lands in the middle of the migration silently turns a cell that already has its recorded decision into one nobody audited, so “every excluded cell has a recorded decision” can be true at the trial and false by cutover without either step's owner noticing.
- “Live use is provably zero” (Step 3) is usually checked against recent traffic, and a periodic consumer, a monthly batch job or an annual report, can pass that check while it is simply between runs. Decommissioning on that reading retires a source that a consumer from Step 1's inventory is still going to call.