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 |