Migration Guide

Transform tool/framework switches from risky leaps into controlled, reversible transitions.

Purpose

Migrations fail when users try to switch everything at once. This skill creates phased migration plans that maintain productivity while transitioning, with rollback options at each phase.

Migration Categories

1. Tool Migration:
   - IDE: Cursor → Claude Code
   - AI: Copilot → Claude
   - Bundler: Webpack → Vite

2. Framework Migration:
   - React → Next.js
   - Express → Fastify
   - REST → GraphQL

3. Workflow Migration:
   - Manual → Automated
   - Monolith → Microservices
   - Local → Cloud

4. Version Migration:
   - Major upgrades (v1 → v2)
   - Breaking changes
   - Deprecation handling

---

Process

Phase 1: Migration Assessment

Entry Check

IF user provided: current state + target state + reason
    → Proceed to Phase 2
ELSE
    → Assess migration scope first

Assessment Questions

Migration Type Detection

IF source and target can coexist:
    → Recommend: Parallel Migration (lowest risk)
    → Run both, gradually shift traffic/usage

IF must be atomic swap:
    → Recommend: Big Bang Migration (higher risk)
    → Requires thorough testing, clear rollback

IF partial migration possible:
    → Recommend: Strangler Fig Pattern
    → New features in new system, old stays

---

Phase 2: Compatibility Mapping

Entry Check

IF migration assessed:
    → Map compatibility
ELSE
    → Return to Phase 1

Feature Mapping Table

## Feature Compatibility

| Feature | [Source] | [Target] | Migration Effort |
|---------|----------|----------|------------------|
| [feature 1] | ✓ How it works | ✓ Equivalent | Low/Med/High |
| [feature 2] | ✓ How it works | ⚠ Different approach | Med |
| [feature 3] | ✓ How it works | ✗ Not available | High (workaround needed) |
| [feature 4] | ✗ N/A | ✓ New capability | Gain |

Breaking Changes Identification

FOR each feature in source:
    Compare with target:

    IF identical API/behavior:
        → Mark: Direct migration

    IF different API, same result:
        → Mark: Adaptation needed
        → Document: transformation required

    IF no equivalent:
        → Mark: Blocker or accept loss
        → Document: workaround or alternative

Dependency Analysis

LIST all dependencies:
    - Which work with both?
    - Which need replacement?
    - Which are source-specific?
    - Which are target-specific?

OUTPUT:
| Dependency | Source | Target | Action |
|------------|--------|--------|--------|
| [dep] | v1.x | v2.x | Upgrade |
| [dep] | ✓ | ✗ | Replace with [alt] |

---

Phase 3: Migration Plan Generation

Entry Check

IF compatibility mapped:
    → Generate phased plan
ELSE
    → Return to Phase 2

Phase Structure

## Migration Plan: [Source] → [Target]

### Phase 0: Preparation (Before Starting)
**Duration:** [estimate]
**Risk:** Low

Actions:
- [ ] Document current configuration
- [ ] Create backup/snapshot
- [ ] Set up target environment
- [ ] Verify team readiness

Rollback: N/A (nothing changed yet)

---

### Phase 1: Parallel Setup
**Duration:** [estimate]
**Risk:** Low

Actions:
- [ ] Install [target] alongside [source]
- [ ] Configure [target] with basic settings
- [ ] Verify [target] works independently
- [ ] Keep using [source] for production work

Rollback: Remove [target], continue with [source]

Success Criteria:
- [Target] runs without errors
- No impact on [source] workflow

---

### Phase 2: Feature Migration
**Duration:** [estimate]
**Risk:** Medium

Actions:
- [ ] Migrate [feature 1] (easiest first)
- [ ] Test [feature 1] in [target]
- [ ] Migrate [feature 2]
- [ ] Test [feature 2] in [target]
- [ ] [Continue for each feature...]

Rollback: Switch back to [source] for migrated features

Success Criteria:
- All migrated features work in [target]
- No data loss or corruption

---

### Phase 3: Workflow Transition
**Duration:** [estimate]
**Risk:** Medium

Actions:
- [ ] Switch primary workflow to [target]
- [ ] Use [source] only for unsupported features
- [ ] Document any gaps or issues
- [ ] Adjust team processes

Rollback: Return to [source] as primary

Success Criteria:
- 80%+ of work done in [target]
- Team comfortable with new workflow

---

### Phase 4: Full Cutover
**Duration:** [estimate]
**Risk:** Low (if previous phases succeeded)

Actions:
- [ ] Disable/uninstall [source]
- [ ] Remove [source] configurations
- [ ] Update documentation
- [ ] Archive [source] backups

Rollback: Reinstall [source] from backup

Success Criteria:
- [Source] fully removed
- No references to [source] in wor

...