refactor-migration_skill

Overview

This skill helps create step-by-step migration plans for refactoring projects that keep the codebase working after each step. It focuses on decomposing changes, defining rollback points, applying feature flags, and mapping incremental deliverables. The goal is to minimize risk while enabling fast feedback and reversible progress.

How this skill works

The skill analyzes a refactor and breaks it into the smallest independently deployable steps, assigning an impact rating (Breaking, High, Medium, Low) to each step. For every step it defines rollback criteria, feature-flag needs, verification checks, and communication points. It produces a milestone-based plan with success criteria, monitoring, and a cleanup timeline for temporary flags and artifacts.

When to use it

• When planning large refactors that must remain deployable at every stage
• When incremental delivery and early value are required
• When coordination across services or teams is needed
• When data or schema changes risk irreversible impact
• When you need clear rollback and monitoring plans

Best practices

• Decompose changes into independently compilable steps; verify tests and builds at each step
• Assign an explicit impact rating for each step and document go/no-go criteria
• Protect risky paths with feature flags; define flag granularity and a removal timeline
• Design rollback strategies that do not require forward-only fixes; test rollback procedures in a staging environment
• Define verification checks (smoke tests, integration tests, metrics) and monitoring alerts for each milestone
• Communicate milestones and expected impacts to dependent teams before each deployment

Example use cases

• Migrating a monolithic API to modular services with phased cutovers and feature flags
• Renaming or reorganizing public interfaces while keeping old adapters until clients migrate
• Applying a database schema change with a reversible data migration and backup strategy
• Introducing a new authentication flow behind a feature flag and gradually enabling it per user cohort
• Parallelizing refactor work across teams with jointly defined integration checkpoints