SKILL.md
Production migration rollout planner
An evidence-first workflow to stage a backwards-compatible application and data migration with safe overlap.
- Revision
- 2
- Verified
- 2026-10-20
Compatibility and paths
Codex
skills/migration-rollout/SKILL.mdClaude Code
.claude/skills/migration-rollout/SKILL.mdVS Code
.github/skills/migration-rollout/SKILL.mdTrust and provenance
Curated record reviewed 2026-10-20. Results still depend on the supplied context and target environment.
Generated assetReady to copy or download
---
name: migration-rollout
description: Plans a data/application rollout with explicit content, completeness and source-writer gates. Use when equal counts or generic rendered pages are being mistaken for a lossless migration; preserve per-record behavior and distinguish public exports from complete backup.
license: CC-BY-4.0
compatibility: Complete owned JSON reconciliation uses Node.js 22.13+ and SHA256 only. No database, files, account, runtime or DNS changes. Actual migration/backup/cutover requires the authorized full state, writer boundary and tested recovery plan.
metadata:
author: oneliners
version: "2.0.0"
---
# Production migration rollout planner
## Inventory what must survive and what can still write
Name source/target versions, schema/runtime/client contracts, public and private state, identities/configuration, jobs and immutable revisions. Record which snapshots are authoritative, their completeness and the write boundary/catch-up design. Preserve actual forms/variables, explanations, steps, FAQ, examples and ordering; do not regenerate diverse records from one old template. A public export is not automatically a complete database backup.
## Complete content-preservation counterexample
The three original fictional records below include different variables, procedures and FAQ. This is not OneLiners production data and does not authorize its migration. Save the complete program as migration-content-fixture.mjs and run node migration-content-fixture.mjs with Node.js 22.13+. Every source/target and manifest input is included; the program has no file, database or network access.
```js
import assert from "node:assert/strict";
import { createHash } from "node:crypto";
const contentSnapshot=[
{
"id": "owned-a",
"slug": "owned-connection",
"revision": 4,
"publishedAt": "2026-01-10",
"variables": [
{
"name": "HOST",
"default": "service.example.invalid"
}
],
"steps": [
{
"id": "check",
"text": "Check the selected endpoint"
},
{
"id": "verify",
"text": "Verify the bounded outcome"
}
],
"faq": [
{
"question": "Which host?",
"answer": "Use the chosen authorized endpoint, not a guessed production host."
}
],
"customNote": "Preserve this original per-record context too."
},
{
"id": "owned-b",
"slug": "owned-restore",
"revision": 2,
"publishedAt": "2026-02-12",
"variables": [],
"steps": [
{
"id": "prepare",
"text": "Prepare an owned restore target"
}
],
"faq": [
{
"question": "Is a backup file enough?",
"answer": "No; a bounded restore still needs verification."
}
],
"customNote": "A different procedure with its own explanation."
},
{
"id": "owned-c",
"slug": "owned-rotation",
"revision": 1,
"publishedAt": "2026-03-15",
"variables": [
{
"name": "TARGET",
"default": "owned-fixture"
}
],
"steps": [
{
"id": "overlap",
"text": "Keep compatible overlap"
},
{
"id": "validate",
"text": "Validate readers and writers"
},
{
"id": "retire",
"text": "Retire only after the gate"
}
],
"faq": [],
"customNote": "Ordered steps are not a set."
}
];
function orderedFixtureJson(value) {
if (value === null || typeof value === "string" || typeof value === "boolean") return value;
if (typeof value === "number") { assert.ok(Number.isFinite(value), "finite JSON numbers only"); return value; }
if (Array.isArray(value)) return value.map(orderedFixtureJson);
assert.ok(value && typeof value === "object" && [Object.prototype, null].includes(Object.getPrototypeOf(value)), "plain JSON only");
return Object.fromEntries(Object.keys(value).sort().map((key) => [key, orderedFixtureJson(value[key])]));
}
function fixturePayloadHash(value) { return createHash("sha256").update(JSON.stringify(orderedFixtureJson(value))).digest("hex"); }
function fixtureCatalogHash(rows) { return fixturePayloadHash([...rows].sort((a, b) => a.id.localeCompare(b.id, "en"))); }
function reconcileContentSnapshot(source, target, manifestSourceHash) {
function inventory(rows) {
const map = new Map();
for (const row of rows) { assert.ok(typeof row.id === "string" && !map.has(row.id), "unique record IDs required"); map.set(row.id, row); }
return map;
}
const before = inventory(source), after = inventory(target), issues = [];
if (fixtureCatalogHash(source) !== manifestSourceHash) issues.push({ kind: "SOURCE_SNAPSHOT_CHANGED" });
for (const [id, row] of before) {
if (!after.has(id)) issues.push({ kind: "MISSING_RECORD", id });
else if (fixturePayloadHash(row) !== fixturePayloadHash(after.get(id))) issues.push({ kind: "PAYLOAD_MISMATCH", id });
}
for (const id of after.keys()) if (!before.has(id)) issues.push({ kind: "UNEXPECTED_RECORD", id });
return { sourceCount: before.size, targetCount: after.size, issues, rowPayloadsMatch: issues.length === 0, gate: issues.length ? "HOLD_CONTENT_OR_SOURCE_MISMATCH" : "PAYLOADS_MATCH_NOT_A_CUTOVER_PROOF", cutoverReady: false, scope: "Owned public JSON rows only; no complete database/private/revision backup, restore, writer checkpoint or runtime migration verified." };
}
function runMigrationContentLab() {
const manifest = fixtureCatalogHash(contentSnapshot);
const damaged = structuredClone(contentSnapshot); damaged[0].variables = []; damaged[1].faq = []; damaged[2].steps.reverse();
const wrong = reconcileContentSnapshot(contentSnapshot, damaged, manifest);
const exact = reconcileContentSnapshot(contentSnapshot, structuredClone(contentSnapshot), manifest);
const sourceMoved = [...structuredClone(contentSnapshot), { id: "owned-d", revision: 1, text: "A later writer published another record." }];
const stale = reconcileContentSnapshot(sourceMoved, structuredClone(contentSnapshot), manifest);
assert.equal(wrong.sourceCount, wrong.targetCount); assert.equal(wrong.issues.length, 3); assert.equal(wrong.rowPayloadsMatch, false);
assert.equal(exact.rowPayloadsMatch, true); assert.equal(exact.cutoverReady, false);
assert.ok(stale.issues.some((issue) => issue.kind === "SOURCE_SNAPSHOT_CHANGED")); assert.ok(stale.issues.some((issue) => issue.kind === "MISSING_RECORD"));
return { damagedTarget: wrong, exactPublicCopy: exact, changedSourceAfterExport: stale };
}
console.log(JSON.stringify(runMigrationContentLab(),null,2));
```
## Worked reconciliation and remaining rollout gates
The damaged target has the same three IDs/counts/revisions as the source, yet all three payloads differ: owned-a lost its variable/form data, owned-b lost its FAQ, and owned-c reversed its ordered procedure steps. A count, a matching title or a working generic page would not establish preserved content. The complete fixture hash comparison detects every mismatch, including fields outside the most visible UI.
An exact public-row copy passes this payload check, but cutoverReady remains false: these rows are not a full database backup with private state, every revision/table, identity mapping, jobs and application/runtime behavior. The local deterministic JSON routine sorts object keys but retains array order. It is a narrow JSON-fixture comparison, not an implementation of a general canonicalization/signature standard or proof of trusted provenance.
When a later source writer adds owned-d, the original manifest hash no longer describes the current source, and the target is also missing that record. HOLD rather than announcing success from the old export. A real migration needs a consistent complete backup/snapshot plus an owner-approved write boundary or verified catch-up/reconciliation process; it cannot be inferred from two public pages sampled at different times.
Plan gates separately: inventory sources/state/config and exact supported clients; restore into private staging; verify per-record payloads/revisions and full database completeness; test old/new reads/writes and bounded backfill/retry/idempotency; verify restore/rollback limits and actual runtime/security flows; switch only after owner-authorized acceptance; retain a working recovery path until contraction is safe. A code revert does not undo newly written data or external side effects. This program reads included JSON in memory only; no database backup, real migration, server/DNS switch or production write occurred.
## Verify completeness and rollback independently
[SQLite backup documentation](https://sqlite.org/backup.html) illustrates consistent database-copy concerns for that engine; use the actual supported export/restore mechanism for the real managed database rather than copying random live files. [Node hashing documentation](https://nodejs.org/api/crypto.html) explains the primitive used here, not authenticity or completeness of a dump. Record the exact compared snapshot/manifest, changed/missing/extra records, complete-table/revision/private-state evidence, old/new application matrix, stage/owner/stop gates and rollback data limits. Never overwrite an improved live revision from a shorter seed, expose secrets in a handoff, or switch runtime/DNS as a side effect of this review.
Real example
Input
Review the complete three-record snapshot and damaged/exact/changed-source cases in SKILL.md. Verify variables, FAQ, ordered steps, all payload metadata and manifest identity; explain why matching public rows/counts do not prove a full database backup or authorize a cutover.
Expected result
The damaged target has the same three IDs/counts/revisions as the source, yet all three payloads differ: owned-a lost its variable/form data, owned-b lost its FAQ, and owned-c reversed its ordered procedure steps. A count, a matching title or a working generic page would not establish preserved content. The complete fixture hash comparison detects every mismatch, including fields outside the most visible UI. An exact public-row copy passes this payload check, but cutoverReady remains false: these rows are not a full database backup with private state, every revision/table, identity mapping, jobs and application/runtime behavior. The local deterministic JSON routine sorts object keys but retains array order. It is a narrow JSON-fixture comparison, not an implementation of a general canonicalization/signature standard or proof of trusted provenance. When a later source writer adds owned-d, the original manifest hash no longer describes the current source, and the target is also missing that record. HOLD rather than announcing success from the old export. A real migration needs a consistent complete backup/snapshot plus an owner-approved write boundary or verified catch-up/reconciliation process; it cannot be inferred from two public pages sampled at different times. Plan gates separately: inventory sources/state/config and exact supported clients; restore into private staging; verify per-record payloads/revisions and full database completeness; test old/new reads/writes and bounded backfill/retry/idempotency; verify restore/rollback limits and actual runtime/security flows; switch only after owner-authorized acceptance; retain a working recovery path until contraction is safe. A code revert does not undo newly written data or external side effects. This program reads included JSON in memory only; no database backup, real migration, server/DNS switch or production write occurred.