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

1. Measure the blast radius

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

1. Choose batch size

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

1. 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

1. 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

1. 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