Quick Migration Assistant

The Quick Migration Assistant command plans and executes systematic migrations between platforms, frameworks, or data formats with comprehensive safety measures, validation checkpoints, and rollback capabilities. It creates migration plans, performs data transformations, validates results at each stage, and provides rollback procedures when issues are detected. Run this command when you need to migrate data, configurations, or entire systems between environments with confidence.

When to Use This Command

Run this command when...

• You are migrating data between platforms such as GitHub to Linear and need a structured plan with validation at each stage
• You need to transform data formats during migration with field mapping, type conversion, and schema alignment
• You want to execute a migration with automatic rollback capability in case validation checks fail at any checkpoint
• You are planning a complex migration and need a detailed runbook that the team can review before execution
• You need to verify migration completeness by comparing source and target data counts, field values, and relationship integrity

Consider alternatives when...

• You are performing a simple one-time data export that does not require validation or rollback capabilities
• Your migration is limited to importing issues, which the dedicated import command handles with optimized batch processing
• You need ongoing synchronization rather than a one-time migration event

Quick Start

Copy
# migration-config.yml
migration:
  name: "github-to-linear-q1"
  source: "github"
  target: "linear"
  phases:
    - plan
    - validate-source
    - transform
    - import
    - validate-target
    - link
safety:
  backup: true
  checkpoints: true
  rollback: "automatic"
  dry-run-first: true

Example invocation:

Copy
/quick-migration-assistant --plan "github-to-linear" --phase execute --backup

Example output:

Migration Execution Report
============================
Migration: github-to-linear-q1
Phase: Execute (with backup)

Pre-flight checks:
  Source connectivity: GitHub API authenticated
  Target connectivity: Linear API authenticated
  Backup created: .migration-backup/2026-03-15/

Phase 1 - Source validation:
  Issues fetched: 342
  Data integrity: Passed (all fields present)

Phase 2 - Transformation:
  Fields mapped: 342/342
  Labels converted: 24 unique labels
  Users mapped: 12/12

Phase 3 - Import:
  Issues created in Linear: 342/342
  Comments transferred: 1,247
  Attachments linked: 89

Phase 4 - Target validation:
  Count match: 342/342 (100%)
  Field integrity: Passed
  Relationship check: Passed

Status: Migration complete
Rollback available: .migration-backup/2026-03-15/

Core Concepts

Concept	Purpose	Details
Phased Execution	Reduce migration risk	Breaks the migration into discrete phases with validation gates between each phase to catch issues early
Backup and Rollback	Enable recovery	Creates backups of target state before migration and provides automated rollback when validation checks fail
Data Transformation	Bridge format differences	Converts data from source schema to target schema with configurable field mapping, type conversion, and value translation
Validation Checkpoints	Verify correctness	Compares source and target data at each phase to ensure counts match, fields are populated, and relationships are preserved
Migration Runbook	Document the process	Generates a human-readable plan that describes each phase, its prerequisites, expected duration, and rollback procedure

Architecture: Migration Pipeline
===================================

+-------------------+     +---------------------+     +------------------+
| Source Validator   | --> | Data Transformer    | --> | Target Importer  |
| (fetch + verify)  |     | (map + convert)     |     | (create + link)  |
+-------------------+     +---------------------+     +------------------+
                                                             |
                          +----------------------------------+
                          v
              +---------------------+     +-------------------+
              | Target Validator    | --> | Rollback Manager  |
              | (count + integrity) |     | (backup + restore)|
              +---------------------+     +-------------------+

Configuration

Parameter	Type	Default	Description
plan	string	required	Migration plan name or template to execute
phase	string	"plan"	Migration phase to run: plan for runbook generation, execute for full migration, validate for post-migration checks
backup	boolean	true	Create a backup before executing migration operations
dry-run	boolean	true	Run the migration without writing to the target system to preview results
rollback-on-failure	boolean	true	Automatically roll back changes if any validation checkpoint fails during execution

Best Practices

1. Generate and review the migration plan before execution. Run the command in plan mode first to produce a detailed runbook that describes every step, prerequisite, and validation checkpoint. Have the team review this plan to catch assumptions, missing steps, or risk factors before any data is moved.

2. Always execute a dry run before the real migration. The dry-run mode performs every transformation and validation step without writing to the target system. This reveals data conversion issues, mapping gaps, and unexpected edge cases without affecting any real data.

3. Create backups at every checkpoint, not just at the start. A single initial backup becomes insufficient when the migration modifies the target incrementally across multiple phases. Checkpoint backups enable rolling back to any intermediate state rather than only to the beginning.

4. Validate both data completeness and data integrity. Count matching ensures no items were lost during migration, but it does not guarantee that field values transferred correctly. Validate both the total count and a sample of individual records with field-level comparison to catch transformation errors.

5. Preserve migration artifacts for post-migration support. Keep the migration logs, mapping files, backup archives, and runbook accessible after the migration completes. These artifacts are invaluable for debugging issues that surface days or weeks after the migration when the immediate context has faded.

Common Issues

Transformation rules fail on edge case data. Migration rules designed for typical data may break on edge cases such as empty fields, special characters in titles, or extremely long descriptions. Test transformations against the full source dataset in dry-run mode to catch edge cases before they cause failures during live execution.

Target validation reports count mismatches due to deduplication. If the target system already contains items that match incoming migration data, the import phase may skip duplicates, causing the target count to be lower than the source count. Account for pre-existing items in your validation logic and distinguish between skipped duplicates and genuinely missing items.

Rollback fails when the target system does not support bulk deletion. Some platforms limit the rate or volume of delete operations, making automated rollback slow or impossible for large migrations. Test the rollback procedure on a small subset before running the full migration to verify that recovery is feasible within acceptable time constraints.