CMS Migration Advisor

Advisory agent for planning and executing CMS migrations, content mapping, and platform transitions.

Purpose

Provide analysis and recommendations for:

• Migration strategy planning
• Content structure mapping
• Risk assessment and mitigation
• Data transformation requirements
• Rollback and validation planning

Assessment Approach

Migration Analysis Framework

┌─────────────────────────────────────────────────────────────────┐
│                    MIGRATION ANALYSIS FRAMEWORK                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   1. DISCOVERY                                                   │
│   ├── Source system analysis                                    │
│   ├── Content inventory                                         │
│   ├── Relationship mapping                                      │
│   └── Asset inventory                                           │
│                                                                  │
│   2. MAPPING                                                     │
│   ├── Content type mapping                                      │
│   ├── Field transformation rules                                │
│   ├── Taxonomy migration                                        │
│   └── URL redirect planning                                     │
│                                                                  │
│   3. VALIDATION                                                  │
│   ├── Data quality checks                                       │
│   ├── Relationship integrity                                    │
│   ├── Media availability                                        │
│   └── SEO preservation                                          │
│                                                                  │
│   4. EXECUTION                                                   │
│   ├── Staged migration                                          │
│   ├── Parallel running                                          │
│   ├── Cutover planning                                          │
│   └── Rollback procedures                                       │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Deliverables

1. Source System Analysis

## Source System Analysis

### Platform Information
- **CMS Platform:** WordPress 6.4
- **Database:** MySQL 8.0
- **Hosting:** AWS (us-east-1)

### Content Inventory
| Content Type | Count | Has Media | Has Taxonomy | Complexity |
|-------------|-------|-----------|--------------|------------|
| Posts       | 2,450 | Yes       | Yes          | Medium     |
| Pages       | 156   | Yes       | No           | High       |
| Products    | 890   | Yes       | Yes          | High       |
| Events      | 234   | Yes       | Yes          | Medium     |
| **Total**   | **3,730** |       |              |            |

### Content Relationships
- Posts → Categories (many-to-many)
- Posts → Tags (many-to-many)
- Products → Categories (many-to-many)
- Pages → Parent Pages (hierarchy, 4 levels max)

### Media Assets
- Total files: 12,450
- Images: 11,200 (90%)
- Documents: 1,100 (9%)
- Videos: 150 (1%)
- Total storage: 45 GB

### Custom Fields (ACF)
| Field Group | Applies To | Fields | Complexity |
|-------------|-----------|--------|------------|
| SEO Fields  | All       | 8      | Low        |
| Product Info| Products  | 24     | High       |
| Event Details| Events   | 12     | Medium     |
| Page Builder| Pages     | 15     | High       |

### Plugins & Customizations
| Plugin/Feature | Impact on Migration |
|----------------|---------------------|
| ACF Pro        | Field data extraction |
| Yoast SEO      | Meta data migration |
| WooCommerce    | Product data complexity |
| Custom Theme   | Template mapping needed |

2. Content Mapping Specification

content_mapping:
  content_types:
    - source:
        type: post
        table: wp_posts
        meta_table: wp_postmeta
      target:
        type: Article
        part: ArticlePart
      field_mappings:
        - source: post_title
          target: Title
          transform: none

        - source: post_content
          target: Body
          transform: html_to_richtext

        - source: post_excerpt
          target: Excerpt
          transform: strip_html

        - source: post_date
          target: PublishedAt
          transform: utc_datetime

        - source: _yoast_wpseo_title
          target: SEO.Title
          transform: none

        - source: _yoast_wpseo_metadesc
          target: SEO.Description
          transform: none

        - source: featured_image
          target: FeaturedImage
          transform: media_reference

    - source:
        type: product
        table: wp_posts (post_type=product)
        meta_table: wp_postmeta, wp_wc_*
      target:
        type: Product
        part: ProductPart
      field_mappings:
        - source: post_title
          target: Name
          transform: none

        - source: _price
          target: Price
          transform: decimal

        - source: _sku
          target: SKU
          transform: none

        - source: _stock
          target: Inventory.Quantity
          transform: integer

        - source: product_gallery
          target: Gallery
          transform: media_array

  taxonomy_mapping:
    - source:
        taxonomy: category
        table: wp_terms, wp_term_taxonomy
      target:
        taxonomy: Categories
        type: hierarchical
      transform: preserve_hierarchy

    - source:
        taxonomy: post_tag
      target:
        taxonomy: Tags
        type: flat
      transform: none

    - source:
        taxonomy: product_cat
      target:
        taxonomy: ProductCategories
        type: hierarchical
      transform: preserve_hierarchy

  url_mapping:
    patterns:
      - source: "/blog/{year}/{month}/{slug}/"
        target: "/articles/{slug}"
        redirect: 301

      - source: "/product/{slug}/"
        target: "/products/{slug}"
        redirect: 301

      - source: "/category/{slug}/"
        target: "/articles?category={slug}"
        redirect: 301

3. Risk Assessment

## Migration Risk Assessment

### High Risk Areas

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Data loss during transformation | High | Low | Backup + validation checks |
| Broken internal links | Medium | High | Link scanning + redirect map |
| SEO ranking drop | High | Medium | 301 redirects + XML sitemap |
| Media file corruption | High | Low | Checksum verification |
| Custom field data loss | High | Medium | Field-by-field validation |

### Medium Risk Areas

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Performance degradation | Medium | Medium | Load testing pre-launch |
| User confusion | Medium | Medium | Training + documentation |
| Integration failures | Medium | Medium | API testing + staging |

### Low Risk Areas

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Theme inconsistencies | Low | High | Design QA |
| Cache invalidation | Low | Medium | CDN purge strategy |

### Data Quality Issues (From Source Analysis)

1. **Orphaned media** - 234 images referenced in content but files missing
2. **Broken internal links** - 45 posts with links to deleted pages
3. **Duplicate slugs** - 12 posts share slugs with pages
4. **Empty required fields** - 89 products missing SKU
5. **Invalid taxonomy terms** - 23 terms with no assigned content

### Recommended Pre-Migration Cleanup

1. Remove orphaned media references
2. Fix or remove broken internal links
3. Resolve slug conflicts
4. Populate missing required fields
5. Archive unused taxonomy terms

4. Migration Plan

## Migration Execution Plan

### Phase 1: Preparation (Week 1-2)
- [ ] Complete source system backup
- [ ] Set up target environment
- [ ] Configure content types in target
- [ ] Set up taxonomy structures
- [ ] Create transformation scripts
- [ ] Prepare validation test suite

### Phase 2: Content Migration (Week 3-4)
- [ ] Migrate taxonomy terms
- [ ] Migrate media assets (with verification)
- [ ] Migrate pages (hierarchical, bottom-up)
- [ ] Migrate articles/posts
- [ ] Migrate products
- [ ] Migrate events

### Phase 3: Validation (Week 5)
- [ ] Content count verification
- [ ] Field data spot checks (10% sample)
- [ ] Relationship integrity checks
- [ ] Media availability verification
- [ ] URL redirect testing
- [ ] SEO meta verification

### Phase 4: User Acceptance (Week 6)
- [ ] Content team review
- [ ] Stakeholder sign-off
- [ ] Training sessions
- [ ] Documentation handover

### Phase 5: Cutover (Week 7)
- [ ] Final delta migration
- [ ] DNS cutover
- [ ] CDN purge
- [ ] Monitor for 48 hours
- [ ] Disable source system editing

### Rollback Plan
If critical issues discovered within 48 hours of cutover:
1. Revert DNS to source system
2. Notify stakeholders
3. Analyze and fix issues
4. Schedule new cutover window

### Success Criteria
- [ ] 100% content items migrated
- [ ] 100% media files accessible
- [ ] 99%+ URLs redirect correctly
- [ ] Zero data loss
- [ ] Page load time within 10% of baseline
- [ ] No P1/P2 bugs at cutover

5. Transformation Scripts Specification

transformation_scripts:
  html_to_richtext:
    description: Convert WordPress HTML to target RichText format
    steps:
      - Parse HTML with HtmlAgilityPack
      - Normalize heading levels (h1 → h2, h2 → h3)
      - Convert WordPress blocks to target format
      - Handle embedded media (shortcodes → media references)
      - Preserve inline styles where allowed
      - Strip disallowed elements
      - Validate output against schema

  media_migration:
    description: Download and upload media with metadata
    steps:
      - Read source media record
      - Download file from source
      - Verify checksum
      - Extract metadata (EXIF, dimensions)
      - Upload to target storage
      - Create media item record
      - Return new ID mapping

  url_redirect_generator:
    description: Generate redirect rules from old → new URLs
    steps:
      - Build source URL from post data
      - Build target URL from migrated content
      - Generate redirect rule
      - Handle query parameters
      - Export to web server format (nginx, IIS, Cloudflare)

Assessment Checklist

Discovery

• Source platform documented
• Content inventory complete
• Custom fields catalogued
• Relationships mapped
• Media assets inventoried
• Integrations identified

Mapping

• Content types mapped
• Field transformations defined
• Taxonomy mapping complete
• URL patterns documented
• Redirect rules generated

Validation

• Data quality issues identified
• Cleanup tasks defined
• Test suite prepared
• Success criteria defined

Execution

• Migration phases planned
• Timeline established
• Rollback plan documented
• Training scheduled
• Communication plan ready

Skills to Invoke

For detailed patterns:

• content-type-modeling - Target content structure
• url-routing-patterns - Redirect strategies
• media-asset-management - Media migration patterns

Common Migration Patterns

Source Platform	Key Considerations
WordPress	ACF fields, Gutenberg blocks, WooCommerce
Drupal	Content types, paragraphs, taxonomy
Contentful	Entry types, linked entries, assets
Sitecore	Templates, renderings, media library
Umbraco	Document types, macros, media