Migrations and upgrades

When to use it

Plan, debug, implement or review WordPress schema and data upgrades: dbDelta tables, versioned migrations, batched backfills, partial failures, multisite and HPOS transitions, search-replace, PHP/WordPress version upgrades and rollback readiness.

Boundaries and hand-offs

WP-CLI runbook mechanics to wp-devkit-wpcli-and-ops; plugin activation/hook lifecycle design to wp-devkit-plugin-development; WooCommerce order API details to wp-devkit-woocommerce-dev; release pipeline and rollback of packages to wp-devkit-ci-cd-and-release-engineering; query speed of the backfill to wp-devkit-performance-review.

Ask Claude

With the plugin loaded, start a read-only review of a bounded target:

/wp-devkit:migration-review <target-path>

The short form /wp-devkit:migration requests a quick scan.

Ask Codex, ChatGPT or Antigravity

Name the installed skill and keep the request bounded. Replace the target with your files or journey.

$wp-devkit-migration-upgrade-review
Review the target without editing files.
Read the project instructions and the skill's engineering contract first.
Separate confirmed findings from candidates and state the evidence and checks you could not run.

What it covers

The agent loads only the reference that matches the task:

• backfill-and-batching.md: cursors, batch sizing, idempotency, locks, checkpoints, verification, Action Scheduler and WP-CLI runners. Read for data rewrites and large tables.
• migration-upgrade-review-workbook.md: Migration and upgrade review workbook
• multisite-and-storage-transitions.md: network vs site upgrades, new-site hooks, HPOS migration, serialized data and search-replace, option/meta/post-type changes. Read when scope is multisite, WooCommerce orders or URL/domain changes.
• platform-upgrades-and-rollback.md: WordPress/PHP/MySQL version upgrades, auto-update rollback limits, backups and restore drills, uninstall and downgrade policy. Read for upgrade planning and recovery.
• schema-and-dbdelta.md: dbDelta rules and limits, collation, indexes, online DDL cost, schema versions, expand/contract. Read for any table or column change.

How a review runs

1. State the invariant: what must be true of the data after migration, and the old and new representations. Identify authoritative storage, site scope, concurrent writers and readers (old code, new code, WP-CLI, cron, REST).
2. Find the trigger and the completion marker. Activation hooks do not run on ordinary updates; the update path must compare a stored version on a hook that runs for updates (typically plugins_loaded or init) and also covers manual, auto-update and multisite paths. Record the version only after the invariant holds.
3. Check schema changes: additive and compatible during overlap, dbDelta formatting, resulting indexes/types, engine behavior, lock time on the real table size. DDL commits implicitly in MySQL/MariaDB, so a transaction wrapper is not rollback.
4. Check the backfill: stable selection and cursor, bounded batch by rows and time, resumability, idempotency, behavior when eligibility changes during the run, treatment of invalid historic values, concurrency control (lock with owner/expiry), progress persisted after committed work.
5. Check cutover and recovery: dual read/write or compatible reads until verified; verification queries (counts, checksums, sampled values); what restoring old code does (nothing to data); backup/restore rehearsal; contract phase deferred to a later release.
6. Check scope: multisite (per-site vs network), HPOS vs legacy order storage, serialized data, uninstall behavior, and the supported WordPress/PHP range.
7. Report findings with a reproduction on a disposable dataset where possible; otherwise classify as candidate with the missing evidence. Read references/migration-upgrade-review-workbook.md for severity, the finding template, false positives and acceptance checks.

What you get back

Lead with the verdict and reviewed scope. Per finding: severity, file:line, trigger (install, update, manual run, multisite, concurrent worker), failure path, data impact, confidence, minimal remediation and a regression. Separate candidates and missing evidence. List executed checks (command, exit status) and unexecuted ones (production-size run, real restore, concurrent workers). For implementation, add stages, verification queries and results, and rollback instructions. "Code can be rolled back" is never a data-recovery claim.

Where to go next

Use review to fix for a bounded implementation and Doctor and reports for environment and evidence tooling.