rampstackco--claude-skills/workflows/migration-with-verification.md

Migration with Verification

name:            Migration with Verification
slug:            migration-with-verification
tier:            forward-deployed (operations)
role:            fde
status:          template
score:           47 (demand 4, pain 5, differentiation 4, usability 4, connectors 4)
intent:          migrate a property with the redirect map gated for completeness, old and
                 new parity proven, cutover staged behind a human, and recovery watched
                 against baselines pre-registered before the flip
when to use:     moving a property to a new domain, platform, or URL structure, where old
                 URLs carry traffic and rankings worth keeping
when not to use: verifying a single deploy on an unchanged property (Post-Deploy Live
                 Verification); a traffic drop with no known cause (Traffic-Drop Triage)
validation note: gated on a real migration of a designated property; none is planned, so
                 it holds at template until such a migration occurs

Connectors

connectors:
  - capability:  crawl.read
    access:      read            # both the old and the new property
  - capability:  search-performance.read
    access:      read            # the pre-cutover baselines
  - capability:  repo.change
    access:      write-held      # the redirect map and any fix land as held changes

Read-only until the held redirect map and fixes. The cutover itself, the DNS and platform actions, is a human phase; nothing here flips a property.

Prerequisites

• Claude with the catalog installed: /plugin marketplace add rampstackco/claude-skills
• Crawl access to both the old property and the new one.
• The complete list of old URLs, from the old sitemap, the crawl, and the search-performance export together, because any one alone misses pages.
• Search-performance history for the old property, to pre-register baselines before cutover.
• The cutover runbook's platform access (DNS, hosting), held by the human who performs it.

Phases

Phase 1: Inventory and pre-register the baselines · lane: convergent (Tholo)

Skills: content-migration, seo-technical Capability class: migration.baseline (substitute equivalents if off-catalog) Input: the old property (crawl.read), its search-performance history, the new property's planned structure Run:

Invoke content-migration to inventory the old property and seo-technical to
read its structure. Build the complete old-URL list as the union of the
sitemap, the crawl, and the search-performance export, because any single
source misses pages. Then PRE-REGISTER the baselines before cutover: the
traffic and ranking levels per key segment, and the recovery metric (which
segment, back to what level, measured over what window) written down now,
while the old property is still live. Produce the inventory and the
pre-registered baseline record.

Output artifact: the complete old-URL inventory and the pre-registered baseline record (traffic, rankings, the recovery metric), dated before cutover Done when: every old URL is inventoried from the three sources unioned, and the baselines and recovery metric are recorded before any cutover step Fails look like: baselines chosen after cutover. A recovery metric written once traffic has moved is fitted to whatever happened and will always find recovery; the baseline means something only if it predates the flip.

Phase 2: Redirect-map completeness gate · lane: gate (Basano)

Skills: content-migration Capability class: migration.redirect-completeness (substitute equivalents if off-catalog) Input: the complete old-URL inventory; the new property's URL structure Run:

Invoke content-migration against the old-URL inventory. For EVERY old URL, not
a sample, assign one of three dispositions: a 301 to a specific new URL,
gone-with-intent (a 410 or an intentional removal with the reason recorded),
or explicitly dropped with a written rationale. The gate is completeness: an
old URL with no disposition is a fail, and the map is not done until the
uncovered count is zero. Report the map with its coverage and every
disposition's evidence. This gate reports and fixes nothing.

Output artifact: the redirect map (every old URL, its disposition, the rationale for drops) with a zero-uncovered coverage report Done when: every old URL in the inventory carries a disposition, the uncovered count is zero, and each drop has a recorded rationale Fails look like: a sampled map. A redirect map spot-checked instead of completed passes review and drops the long tail, and the long tail is where the accumulated ranking equity quietly lived.

Phase 3: Parity audit, old versus new · lane: gate (Basano)

Skills: seo-technical, seo-onpage Capability class: migration.parity-audit (substitute equivalents if off-catalog) Input: the old and new properties (crawl.read); the redirect map Run:

Invoke seo-technical and seo-onpage against matched old and new URLs. For each
mapped pair, check parity: title and meta, the canonical target, structured
data, the presence of the content the old page ranked for, and the
internal-link graph around it. Flag any new page that lost metadata, changed a
canonical away from itself, dropped structured data, or is missing content its
old counterpart carried. Report parity per pair with the evidence. Report only.

Output artifact: the parity report (each mapped pair, per-check verdict, the evidence) Done when: every mapped pair has a parity verdict across metadata, canonical, structured data, content presence, and internal links Fails look like: parity by URL existence. A new URL that returns 200 can still have lost the title, the schema, and half the body the old one ranked for, and a check that stops at "the page exists" certifies a page that will not hold the ranking.

Phase 4: Staged cutover · lane: divergent (human)

Skills: launch-runbook Capability class: migration.cutover (write-held runbook; the actions are human) Input: the passing redirect map and parity report Run:

Invoke launch-runbook to author the staged cutover runbook: the ordered DNS
and platform steps, each stage with a checkpoint that must pass before the
next. Then a person performs the cutover per the runbook; DNS and platform
changes are production state changes and stay human. The human records which
stage was executed when, and holds at any checkpoint that fails rather than
proceeding.

Output artifact: the staged cutover runbook, and the human's record of each stage executed with its checkpoint result Done when: the cutover stages are executed per the runbook with each checkpoint recorded, or the cutover is held at a failed checkpoint Fails look like: a big-bang cutover with no checkpoints. Flipping everything at once removes the one thing staging buys, the chance to catch a broken stage before the next one lands on top of it.

Phase 5: Post-cutover verification · lane: gate (Basano)

Skills: none; the engine is the Post-Deploy Live Verification workflow, executed as written Capability class: deploy.live-verify (delegated to Post-Deploy Live Verification) Input: the new property; the redirect map Run:

Run Post-Deploy Live Verification as written against the new property's touched
and blast-radius routes. Do not restate its procedure here: it owns the
discriminator value, the build-identity read, and the two-fetch production
discipline, and this phase inherits all of it. Then add the migration-specific
check: verify the redirect map fires on the live property, the highest-traffic
and the gone-with-intent URLs first, each old URL landing on its mapped target
with the right status code. Report the live-verification verdict and the
redirect verdicts together.

Output artifact: the Post-Deploy Live Verification closure for the new property plus the live redirect verdicts from the map Done when: Post-Deploy Live Verification closes VERIFIED on the new property and the mapped redirects fire live with the right status codes, or the discrepancies are filed with their evidence Fails look like: declaring the migration done at the DNS flip. DNS resolving is not the property migrated; the redirects, the parity, and the live render are, and only production fetches prove them.

Phase 6: Monitoring window against the pre-registered baselines · lane: gate (Basano)

Skills: seo-rank-tracking, seo-traffic-diagnosis Capability class: migration.monitor (substitute equivalents if off-catalog) Input: the pre-registered baseline record; the new property's search-performance and ranking data on a cadence Run:

Invoke seo-rank-tracking and seo-traffic-diagnosis against the new property on
a fixed cadence through the monitoring window. Measure the affected segments
against the baselines pre-registered in Phase 1, and report the trajectory.
Declare the migration recovered only when the pre-registered recovery metric
holds across its pre-registered window, not on the first good week. If the
trajectory contradicts the baseline, the migration has a regression and it
routes out of this workflow.

Output artifact: monitoring reports on cadence, and a closure record when the pre-registered recovery condition holds Done when: the pre-registered recovery condition holds across its window and the closure is recorded, or the window breaks baseline and the regression is routed to Traffic-Drop Triage Fails look like: closing on the first good week. Migration traffic is noisy in the weeks after cutover, and a recovery declared on one datapoint reopens a month later as a mystery with the trail already cold.

Failure modes

• The redirect map sampled instead of complete (Phase 2's failure): the long tail dropped, and with it the accumulated equity.
• Baselines chosen after cutover (Phase 1's failure): a recovery metric fitted to what happened always finds recovery.
• Declaring success at the DNS flip (Phase 5's failure): cutover is not migration; the redirects, the parity, and the live render are.
• The old property's cache serving past cutover: after the flip, some request paths keep serving the old property's cached render for a while, so a page can look migrated on one fetch and stale on another. Verification covers cookie-less vantages and does not stop at the first clean fetch; a clean read from one path is a sample, not the verdict. This is the split-serving class at its worst possible moment, when two properties are briefly both answering.
• Parity by URL existence (Phase 3's failure): a 200 that lost the title, the schema, and half the body.
• A big-bang cutover (Phase 4's failure): no checkpoint to catch a broken stage before the next lands on it.

Worked example

Pending. Populates when this workflow is executed as written on a real migration of a designated property; none is planned, so it holds at template until such a migration occurs. The split-serving pattern in the failure modes generalizes production incidents on an unnamed property, where a render persisted on one request path after a change while another path served current data; that lesson informs Phase 5's vantage discipline but is not validation evidence. Status flips to validated when a run record links here.

Boundaries

• Post-Deploy Live Verification is Phase 5's engine: this workflow runs it as written against the new property and adds the redirect checks, rather than restating its procedure.
• Traffic-Drop Triage takes over when the monitoring window breaks baseline: a post-cutover regression that contradicts the pre-registered recovery metric is a diagnosable drop, and that workflow owns the diagnosis.