superpowers-sage-migrating

name	superpowers-sage:migrating
description	WordPress migration to Sage/Acorn — migrate classic theme to Sage, incremental migration, 7-phase migration contract, rollback playbook, migration hard gates, functions.php to Service Providers, shortcodes to Blade, CPT registration to Poet, field groups to ACF Composer, safe migration reversible steps, migration output artifacts, legacy plugin to Acorn, wp-content to Bedrock structure, database migration, content migration
user-invocable	true
argument-hint	<migration-name> [target-scope]

Migrating — Safe Destructive Data Operations

Execute data migrations with full safety harness: snapshot, dry-run, gate, apply, verify, confirm idempotency. Never destructive-first.

Announce at start: "I'm using the migrating skill for a safe data migration with snapshot/dry-run/gate/apply/verify/idempotency checks."

When to Use

• post_content rewrites (injecting blocks, replacing shortcodes, updating markup)
• wp_postmeta cleanup (orphan keys, schema changes, re-computing derived values)
• Term taxonomy fixes (renaming, merging, re-assigning terms)
• Attachment regeneration (thumbnails, metadata, rewriting paths)
• User role migrations
• Bulk option updates with serialized data
• Any operation that could lose data if applied incorrectly

When NOT to Use

• Developer-only refactors that don't touch DB data — use /building or direct edits
• Simple one-shot admin tasks — use lando wp directly
• Schema changes at the table level — use Laravel migrations or acorn-eloquent
• Long-running pipelines with failure-retry needs — use acorn-queues with jobs

Input

$ARGUMENTS

Resolve to a migration name (used for snapshot filenames and logs) and target scope.

Hard Gates

• Never apply without snapshot-before. If the snapshot step fails, STOP.
• Never apply without human approval of the dry-run diff. Autonomous apply is forbidden.
• Never declare done without snapshot-after verification proving row counts, field shapes, and spot-check samples match expectations.
• Never leave the migration without idempotency proof. Re-running must be a no-op (0 rows changed).

The 7-Phase Contract

┌─────────────────────────────────────────────────────────┐
│  1. SNAPSHOT BEFORE    → /tmp/<migration>-before.xml    │
├─────────────────────────────────────────────────────────┤
│  2. DRY-RUN COMPUTE    → list affected rows + new shape │
├─────────────────────────────────────────────────────────┤
│  3. HUMAN APPROVAL     → show diff, pause, await 'y'    │
├─────────────────────────────────────────────────────────┤
│  4. PREFLIGHT CHECKS   → orphan meta, template validity │
├─────────────────────────────────────────────────────────┤
│  5. APPLY              → loop, log progress, wp_slash() │
├─────────────────────────────────────────────────────────┤
│  6. SNAPSHOT AFTER     → /tmp/<migration>-after.xml     │
│     + VERIFY           → count + shape + spot-check     │
├─────────────────────────────────────────────────────────┤
│  7. IDEMPOTENCY CHECK  → re-run, assert 0 rows changed  │
└─────────────────────────────────────────────────────────┘

Full phase procedures (commands, scripts, validation criteria): skills/migrating/references/phase-detail.md

Rollback procedures for all 3 tiers: skills/migrating/references/rollback-playbook.md

Rollback (Summary)

If post-verification anything is wrong, use the lowest-impact tier:

• Tier 1 — lando wp post list --post_type=revision --post_parent=<ID> then lando wp post update <ID> --post_content="$(lando wp post get <REVISION-ID> --field=post_content)" (single post, revisions enabled)
• Tier 2 — lando wp db import /tmp/<migration>-postmeta-before.sql (table-level)
• Tier 3 — lando wp db import /tmp/<migration>-full-before.sql (nuclear, last resort)

Always have the Tier 3 snapshot before applying.

Anti-Drift — Don't Do This

Wrong	Correct
Apply first, snapshot after	Snapshot BEFORE apply, always
Skip dry-run ("trust me")	Dry-run + diff always — no autonomous apply
Approve on silence	Explicit 'y' required; silence is not consent
Bulk $wpdb->update() without wp_slash()	wp_slash() for user content
One-shot script with no idempotency check	Re-run after apply, assert 0 updates
Delete target rows before apply	Never; update in place, rollback via snapshot
Skip _wp_page_template preflight	Check orphan meta before wp_update_post
Apply without Tier-3 snapshot	lando wp db export full DB before any destructive op