| name | migration-refactoring |
| version | 0.2.10 |
| category | code-quality |
| description | Automate complex code migrations and refactorings with safety patterns. Use this skill when upgrading dependencies, migrating frameworks (React class→hooks, Flask→FastAPI), modernizing languages (Python 2→3), or performing large-scale refactories — even if they just say "migrate this" or "refactor the whole thing". Includes breaking change analysis, automated fix application, rollback strategies, and cross-file dependency tracking. Not for static-analysis, code-review-assistant. |
| license | MIT |
Migration & Refactoring
Systematic approach to complex code migrations with safety guardrails and rollback capabilities.
When to Use
- Dependency upgrades - Major version bumps with breaking changes
- Framework migrations - React class→hooks, Flask→FastAPI, Django→DRF, etc.
- Language modernizations - Python 2→3, JavaScript→TypeScript
- Large-scale refactoring - Cross-file changes requiring consistency
- Database schema evolution - Migrations with data transformation
- Monorepo decomposition - Extracting services from monoliths
Core Workflow
Phase 1: Analysis
- Identify scope - What files, modules, and dependencies are affected?
- Map dependencies - Create a dependency graph of cross-file relationships
- Find breaking changes - Analyze changelogs, migration guides, deprecation warnings
- Assess risk - Flag high-risk changes (public APIs, critical paths)
Phase 2: Planning
- Create migration plan - Ordered sequence of changes
- Define checkpoints - Intermediate states that compile/work
- Design rollback strategy - How to revert if issues arise
- Estimate effort - Time and complexity assessment
Phase 3: Execution
- Execute in phases - Apply changes incrementally
- Validate at each checkpoint - Test compilation, run tests, verify functionality
- Document changes - Update docs, changelogs, ADRs
- Commit incrementally - Each checkpoint is a commit
Phase 4: Validation
- Run full test suite - Verify nothing broken
- Performance testing - Ensure no regressions
- Code review - Human validation of changes
- Production rollout - Deploy with monitoring
Migration Patterns
Pattern 1: Gradual Migration
Old API → Compatibility Layer → New API → Remove Old
When: Cannot change all call sites at once
Pattern 2: Feature Flags
if (useNewImplementation) {
return newImplementation();
} else {
return oldImplementation();
}
When: High-risk changes needing rollback capability
Pattern 3: Strangler Fig
Monolith → Proxy → New Service
→ Old Monolith
When: Decomposing monoliths incrementally
Pattern 4: Parallel Implementation
Old System (read-only) → Data Sync → New System (write)
When: Zero-downtime migrations with data changes
See references/migration-patterns.md for detailed implementations.
Breaking Change Analysis
Checklist for Upgrades
Common Breaking Changes
| Category | Examples |
|---|
| API Removal | function removed() |
| Signature Changes | func(a, b) → func(a, b, c) |
| Default Changes | encoding='utf-8' → encoding=None' |
| Dependency Drops | Dropped Python 3.8 support |
| Return Type Changes | list → generator |
Cross-File Dependency Tracking
Dependency Graph Elements
- Imports/includes - File A imports File B
- Inheritance - Class A extends Class B
- Interface implementations - Class implements Interface
- Function calls - Function in A calls function in B
Tools by Language
- Python:
pydeps, importlab
- JavaScript/TypeScript:
dependency-cruiser, madge
- Java:
jdeps, classycle
- Go:
godepgraph
- Rust:
cargo-deps
See references/dependency-analysis.md for detailed usage.
Safety Patterns
Snapshot Testing
save_snapshot(test_output, "v1_expected.json")
assert_matches_snapshot(actual_output, "v1_expected.json")
Property-Based Testing
@given(st.data())
def test_migration_preserves_properties(data):
old_result = old_implementation(data)
new_result = new_implementation(data)
assert old_result.property == new_result.property
Canary Deployments
- Deploy to 1% of traffic
- Monitor error rates, latency
- Gradually increase to 100%
- Rollback if issues detected
See references/safety-patterns.md for more patterns.
Rollback Strategies
| Strategy | Best for | Example |
|---|
| Git Revert | Small, isolated migrations | git revert <migration-commit> |
| Feature Flag Disable | Gradual rollouts | USE_NEW_PARSER = False |
| Database Rollback | Schema changes with data loss | ALTER TABLE users DROP COLUMN ... |
See references/rollback-strategies.md for platform-specific guides.
Examples
React Class to Hooks: componentDidMount/componentWillUnmount → useEffect, componentDidUpdate → useEffect with deps, this.state → useState, this.props → destructured.
Python 2 to 3: 2to3 -w --output-dir=src_py3 src/ then fix imports, print, string handling. See references/language-migrations.md.
Quality Checklist
See Also
static-analysis — Linter triage and fix workflowscode-review-assistant — PR review workflow
Rationalizations
| Rationalization | Reality |
|---|
| "We'll migrate everything at once in one big PR" | Big-bang migrations create untestable changesets with no safe rollback point. |
| "The old version still works, no rush to migrate" | Unmaintained dependencies accumulate CVEs and block critical security patches. |
| "Automated tests are enough validation" | Automated tests catch regressions; human review catches design and UX regressions. |
Red Flags
References
references/migration-patterns.md - Detailed pattern implementationsreferences/dependency-analysis.md - Cross-file dependency trackingreferences/language-migrations.md - Framework migration guides
