our-claude-skills/custom-skills/33-seo-migration-planner/code/CLAUDE.md

CLAUDE.md

Overview

SEO site migration planning and monitoring tool for comprehensive pre-migration risk assessment, redirect mapping, URL inventory, crawl baseline capture, and post-migration traffic/indexation monitoring. Supports domain moves, platform changes, URL restructuring, HTTPS migrations, and subdomain consolidation. Captures full URL inventory via Firecrawl crawl, builds traffic/keyword baselines via Ahrefs, generates redirect maps with per-URL risk scoring, and tracks post-launch recovery with automated alerts.

Quick Start

pip install -r scripts/requirements.txt

# Pre-migration planning
python scripts/migration_planner.py --domain https://example.com --type domain-move --new-domain https://new-example.com --json

# Post-migration monitoring
python scripts/migration_monitor.py --domain https://new-example.com --migration-date 2025-01-15 --baseline baseline.json --json

Scripts

Script	Purpose	Key Output
migration_planner.py	Pre-migration baseline + redirect map + risk assessment	URL inventory, redirect map, risk scores, checklist
migration_monitor.py	Post-migration traffic comparison, redirect health, indexation tracking	Traffic delta, broken redirects, ranking changes, alerts
base_client.py	Shared utilities	RateLimiter, ConfigManager, BaseAsyncClient

Migration Planner

# Domain move planning
python scripts/migration_planner.py --domain https://example.com --type domain-move --new-domain https://new-example.com --json

# Platform migration (e.g., WordPress to headless)
python scripts/migration_planner.py --domain https://example.com --type platform --json

# URL restructuring
python scripts/migration_planner.py --domain https://example.com --type url-restructure --json

# HTTPS migration
python scripts/migration_planner.py --domain http://example.com --type https --json

# Subdomain consolidation
python scripts/migration_planner.py --domain https://blog.example.com --type subdomain --new-domain https://example.com/blog --json

Capabilities:

• URL inventory via Firecrawl crawl (capture all URLs + status codes)
• Ahrefs top-pages baseline (traffic, keywords per page)
• Redirect map generation (old URL -> new URL mapping)
• Risk scoring per URL (based on traffic + backlinks + keyword rankings)
• Pre-migration checklist generation
• Support for migration types:
  • Domain move (old domain -> new domain)
  • Platform change (CMS/framework swap)
  • URL restructuring (path/slug changes)
  • HTTPS migration (HTTP -> HTTPS)
  • Subdomain consolidation (subdomain -> subfolder)

Migration Monitor

# Post-launch traffic comparison
python scripts/migration_monitor.py --domain https://new-example.com --migration-date 2025-01-15 --baseline baseline.json --json

# Monitor with custom period
python scripts/migration_monitor.py --domain https://new-example.com --migration-date 2025-01-15 --baseline baseline.json --json

# Quick redirect health check
python scripts/migration_monitor.py --domain https://new-example.com --migration-date 2025-01-15 --json

Capabilities:

• Post-launch traffic comparison (pre vs post, by page group)
• Redirect chain/loop detection
• 404 monitoring for high-value pages
• Indexation tracking (indexed pages before vs after)
• Ranking change tracking for priority keywords
• Recovery timeline estimation
• Alert generation for traffic drops >20%

Ahrefs MCP Tools Used

Tool	Purpose
site-explorer-metrics	Current organic metrics (traffic, keywords)
site-explorer-metrics-history	Historical metrics for pre/post comparison
site-explorer-top-pages	Top performing pages for baseline
site-explorer-pages-by-traffic	Pages ranked by traffic for risk scoring
site-explorer-organic-keywords	Keyword rankings per page
site-explorer-referring-domains	Referring domains per page for risk scoring
site-explorer-backlinks-stats	Backlink overview for migration impact

Output Format

{
  "domain": "example.com",
  "migration_type": "domain-move",
  "baseline": {
    "total_urls": 1250,
    "total_traffic": 45000,
    "total_keywords": 8500,
    "top_pages": []
  },
  "redirect_map": [
    {
      "source": "https://example.com/page-1",
      "target": "https://new-example.com/page-1",
      "status_code": 301,
      "priority": "critical"
    }
  ],
  "risk_assessment": {
    "high_risk_urls": 45,
    "medium_risk_urls": 180,
    "low_risk_urls": 1025,
    "overall_risk": "medium"
  },
  "pre_migration_checklist": [],
  "timestamp": "2025-01-01T00:00:00"
}

Notion Output (Required)

IMPORTANT: All audit reports MUST be saved to the OurDigital SEO Audit Log database.

Database Configuration

Field	Value
Database ID	2c8581e5-8a1e-8035-880b-e38cefc2f3ef
URL	https://www.notion.so/dintelligence/2c8581e58a1e8035880be38cefc2f3ef

Required Properties

Property	Type	Description
Issue	Title	Report title (Korean + date)
Site	URL	Target website URL
Category	Select	SEO Migration
Priority	Select	Based on risk level
Found Date	Date	Report date (YYYY-MM-DD)
Audit ID	Rich Text	Format: MIGR-YYYYMMDD-NNN

Language Guidelines

• Report content in Korean (한국어)
• Keep technical English terms as-is (e.g., Redirect Map, Risk Score, Traffic Baseline, Indexation)
• URLs and code remain unchanged