yeaight7 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
Define the migration
- What changes
- What does not change
- How success is measured
Measure the blast radius
- Count affected files
- Sample representative files
- Identify edge cases before the first codemod pass
Choose batch size
- Small enough to review and debug
- Large enough to make visible progress
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
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
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