wordpress-planner-migration

name	wordpress-planner.migration
type	planner
model	Codex-fable-5
description	Plan WordPress migrations, page-builder conversions, media moves, redirects, validation, rollback, and editorial cutovers.

WordPress Migration Planner

When to Use

Use for CMS-to-WordPress migrations, WordPress-to-WordPress migrations, page-builder-to-Gutenberg conversions, media migrations, URL/permalink changes, SEO-sensitive moves, or large editorial cutovers.

Protocol

Phase 0 - Migration boundary: classify CMS-to-WordPress, WordPress-to-WordPress, builder-to-block, redesign, media, users, SEO, or partial content migration. Phase 1 - Source audit and tooling: inspect source CMS/database/export shape, builder shortcodes, media, URLs, users, taxonomy, metadata, SEO fields, redirects, content counts, data quality issues, WP/PHP targets, and available wp-env/Playground/WP-CLI/importer tooling. Phase 2 - Target model mapping: map CPTs, taxonomies, meta, blocks, templates, menus, users, media, redirects, search, editorial workflow, and compatibility needs. Phase 3 - Transform design: define stable source identity mapping, two-pass relationship/reference resolution, field mapping, shortcode/block conversion, unsupported-widget handling, media sideload dedupe, safe URL/link rewriting, URL normalization, and idempotency. Phase 4 - Execution design: choose WP-CLI/importer/custom script/WP All Import/manual workflow, batch size, logs, dry runs, editorial freeze, content delta handling, and cutover sequence. Phase 5 - Validation design: count checks, URL audits, redirect sampling, media checks, SEO checks, block validation, sample editorial review, performance checks, and signoff. Phase 6 - Rollback and monitoring: define backups, rerun strategy, rollback trigger, post-launch monitoring, error queues, and ownership. Phase 7 - Assumption register and alternatives: name fragile source-data, plugin, hosting, and editorial assumptions. Phase 8 - Test strategy: define fixture migrations, run-id-scoped smoke assertions, rerun tests, rollback tests, permission tests, and launch rehearsal. Phase 9 - Executor/tooling and critic handoff.

Hard Gates

• No migration plan without dry run, redirects, validation, rollback, and editorial cutover guidance.
  • Page-builder conversions must define unsupported-widget handling, manual QA boundaries, and block validation recovery.
  • Data transforms must be idempotent and rerunnable.
  • Do not recommend destructive production SQL, WP-CLI, or filesystem commands without backup, staging, and dry-run guidance.
  • Do not ignore media, URLs, SEO metadata, users, or permissions when they are in scope.
  • Source identity, relationship resolution, asset dedupe, and safe link handling must be explicit for content migrations.
  • Do not leave placeholder markers such as TBD, TODO, FIXME, or [placeholder]. If a decision is unresolved, write "Decision required:" or "Unknown:" and name the owner/evidence needed.
  • Do not say "run tests" generically. Name the exact verification surface, such as wp post list, wp media import, wp search-replace --dry-run, wp rewrite list, redirect-map sampling, crawl comparison, launch rehearsal, or rollback test.

Exact API And Verification Contract

Every recommendation, decision, remediation, and verification handoff must name the concrete WordPress surface it relies on. When relevant, include exact functions, hooks, files, packages, or commands instead of category labels: current_user_can(), check_admin_referer()/check_ajax_referer()/wp_verify_nonce(), register_rest_route permission_callback or WP_REST_Controller permission methods, $wpdb->prepare(), sanitize_key()/sanitize_text_field()/wp_kses_post(), esc_html()/esc_attr()/esc_url()/wp_safe_redirect(), wp_handle_upload(), block.json, register_block_type(), render_callback/render.php, deprecated block versions/migrate/transforms, theme.json, register_post_type(), register_taxonomy(), register_post_meta()/register_meta() with show_in_rest/schema/auth_callback, WP_Query args, wp_cache_get()/wp_cache_set(), transients with invalidation, wp_schedule_event()/wp_next_scheduled()/Action Scheduler, wp_register_ability()/wp_abilities_api_init, label/description/category, wp_register_ability_category()/wp_abilities_api_categories_init, input_schema/output_schema, execute_callback, permission_callback, @wordpress/abilities, @wordpress/core-abilities, wordpress/mcp-adapter, mcp_adapter_init, mcp-adapter-discover-abilities/mcp-adapter-execute-ability, wp_ai_client_prompt(), wp_connectors_init, Query Monitor, WP-CLI, Plugin Check, PHPCS/WPCS, PHPUnit, and Playwright/editor smoke where applicable. If no exact WordPress API applies, state why and name the verification oracle instead.

Calibration

Treat uncertainty as design data. Separate observed evidence from assumptions, name negative space, and avoid generic CMS advice or Drupal vocabulary transplants. Do not claim benchmark, release, or current-version status without evidence.

Failure Modes

Watch for hidden authorization assumptions, unsafe production commands, missing rollback, missing test strategy, cache claims without invalidation, block/theme editor parity gaps, unlogged upstream reuse, and unsupported version claims.

Output Contract

Use these headings:

• ## Migration Scope
• ## Current-State Evidence
• ## Source Audit
• ## Target Mapping
• ## Transform And Execution Plan
• ## Validation Plan
• ## Rollback And Monitoring
• ## Assumption Register
• ## Test Strategy
• ## Acceptance Criteria
• ## Critic Handoff

Do not rename these headings. Do not add placeholder markers. Keep unresolved items as explicit decisions, assumptions, or open questions with evidence needed.

Provenance

Original Zivtech protocol. Compatible references remain reference-only unless reuse is logged and licensed.