playbooks

home / skills / shotaiuchi / dotclaude / refactor-migration

refactor-migration skill

/dotclaude/skills/refactor-migration

This skill guides incremental refactor migration planning, enabling safe stepwise changes, rollback readiness, feature flags, and measurable delivery

npx playbooks add skill shotaiuchi/dotclaude --skill refactor-migration

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.0 KB
---
name: refactor-migration
description: >-
  Step-by-step migration planning for refactoring. Apply when creating
  incremental migration plans, defining rollback points, feature flags,
  and ensuring each step leaves code in a working state.
user-invocable: false
---

# Migration Planner Analysis

Create a step-by-step migration plan that ensures each step leaves the codebase in a working state.

## Analysis Checklist

### Step Decomposition
- Break the refactoring into the smallest independently deployable steps
- Verify each step produces a compilable and testable codebase
- Order steps to minimize risk and maximize early feedback
- Identify steps that can be parallelized across team members

### Rollback Points
- Define clear rollback criteria for each migration step
- Ensure rollback does not require forward-fixing other changes
- Verify data migrations are reversible or have backup strategies
- Plan rollback testing as part of the migration process

### Feature Flag Strategy
- Identify changes that benefit from feature flag protection
- Design flag granularity (per-feature, per-component, per-user)
- Plan flag cleanup timeline to avoid permanent toggles
- Ensure both old and new code paths remain tested

### Incremental Delivery
- Map migration steps to deployable milestones
- Define success criteria and verification for each milestone
- Plan communication points for dependent teams
- Identify minimum viable migration for early value delivery

### Risk Mitigation
- Identify steps with highest failure probability
- Plan fallback strategies for each high-risk step
- Define monitoring and alerting for migration progress
- Establish go/no-go criteria for proceeding to next step

## Output Format

Report findings with impact ratings:

| Impact | Description |
|--------|-------------|
| Breaking | Step that cannot be rolled back without data loss |
| High | Step requiring coordinated deployment across services |
| Medium | Step with moderate risk, rollback plan available |
| Low | Safe step with straightforward rollback |

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

FAQ

How do you choose impact ratings for steps?

Rate based on reversibility and coordination needs: Breaking for irreversible data changes, High for multi-service deploys, Medium for changes with tested rollbacks, Low for isolated, easily reverted steps.

When should feature flags be removed?

Plan a cleanup timeline tied to usage and verification milestones; remove flags once all consumers are migrated and tests cover the new path.