/codebase-migration-batches

name: codebase-migration-batches
description: Use when a wide refactor or migration is too large to ship as one change — API renames across many files, framework or config migrations, or mechanical codemod-backed refactors that need reviewable batches.

Codebase Migration Batches

Use this skill for broad, repetitive refactors that should move in slices.

When to Use

• API renames across many files
• Framework or config migrations
• Mechanical refactors backed by codemods or search/replace rules
• Any change where "all at once" would be too large to review safely

Core Rules

• Define the transform precisely before editing files
• Keep one migration theme per batch
• Prefer deterministic codemods over manual repetition
• Maintain a batch ledger so already-migrated files are not touched twice
• Validate each batch before moving to the next
• No auto-commit, auto-push, or auto-PR

Workflow

1. **Define the migration**

• What changes
• What does not change
• How success is measured

2. **Measure the blast radius**

• Count affected files
• Sample representative files
• Identify edge cases before the first codemod pass

3. **Choose batch size**

• Small enough to review and debug
• Large enough to make visible progress

4. **Run the transform**

• Prefer AST-aware tools when syntax matters
• Use plain search/replace only for truly mechanical edits
• Keep any helper scripts under versioned project control if they are reused

5. **Verify the batch**

• Run targeted tests first
• Run broader validation when the batch changes shared primitives
• Track residual manual fixes separately from the codemod logic

6. **Advance or stop**

• Continue if the batch is stable
• Shrink the batch if review or validation gets noisy
• Stop and redesign the transform if repeated manual cleanup dominates

Batch Ledger

Track at least:

Batch ID
Files included
Transform rule
Validation run
Known exceptions

Verification

• [ ] The transform was defined precisely — what changes, what does not — before the first file edit
• [ ] Each batch held one migration theme and passed validation before the next began
• [ ] The batch ledger records files, transform rule, validation run, and exceptions for every batch
• [ ] No already-migrated file was touched twice; no auto-commit, auto-push, or auto-PR occurred