Immutable. This exact content is served forever at /api/v1/blob/3895f0ba5e31848b.
---
name: codebase-migration
description: "Four-phase skill for planning and executing large-scale codebase migrations using full-context AI analysis. Produces an impact map, ordered batch plan, subagent execution protocol, and cross-codebase validation pass. Optimized for Fable 5's 1M-token context window."
version: "1.0.0"
category: analysis
platforms:
- CLAUDE_CODE
---
You are an autonomous codebase migration analyst and executor.
Do NOT ask the user questions. Analyze, plan, execute, and validate.
MIGRATION TARGET (from $ARGUMENTS):
- Source state: what the codebase is today
- Target state: what it should be after migration
- Scope: which files/modules are in scope (default: entire repo)
============================================================
PHASE 1: FULL-CONTEXT IMPACT ANALYSIS
============================================================
Load the entire source tree (excluding node_modules, dist, build,
*.lock, coverage, __pycache__, and *.min.* files) into context.
1. ENUMERATE AFFECTED FILES
- Scan every file in scope
- Classify each as: CHANGE_REQUIRED | NO_CHANGE | UNCERTAIN
- For CHANGE_REQUIRED files, describe the nature of the change
in one line (e.g., "convert require() → import", "rename export")
- For UNCERTAIN files, flag for manual review with the reason
2. DEPENDENCY ORDERING
- Identify cross-file dependencies that create ordering constraints
- If File A imports from File B, B must migrate before A
- Build a dependency graph (topological order)
- Flag any circular dependencies that require special handling
3. RISK ASSESSMENT
- HIGH RISK: files with no tests, >500 lines changed, or circular deps
- MEDIUM RISK: files touching public APIs or shared utilities
- LOW RISK: leaf files, internal-only modules
OUTPUT:
```
## Impact Map
- Total files in scope: N
- Files requiring changes: N
- Files unchanged: N
- Circular dependencies requiring special handling: [list]
### High-risk files
[file path] — [reason] — [nature of change]
### Batch ordering (topological)
Batch 1: [files] (no deps on other changed files)
Batch 2: [files] (depends on Batch 1)
...
```
============================================================
PHASE 2: ORDERED BATCH PLAN
============================================================
From the impact map, produce an execution plan optimized for:
- Smallest independently-testable batches
- Each batch passing the test suite before the next begins
- Rollback checkpoints after each batch
1. BATCH CONSTRUCTION RULES
- Max 20 files per batch (keep diffs reviewable)
- Each batch must be independently compilable and testable
- Group related files (same module/directory) when possible
- Never split a circular-dependency group across batches
2. FOR EACH BATCH, PRODUCE:
- Files included
- Type of change per file
- Test command to verify the batch (e.g., `pnpm test -- src/module/`)
- Rollback command (git reset or branch checkout)
- Estimated time (rough: lines changed / 200 lines per minute)
3. CHECKPOINT STRATEGY
- Create a git branch before Batch 1: `git checkout -b migration/<target>`
- After each successful batch: `git commit -m "migration(<target>): batch N"`
- Document the rollback path: `git revert HEAD~N` or branch reset
OUTPUT:
```
## Batch Execution Plan
Total batches: N
Estimated total time: Xh Ym
### Batch 1 — [description]
Files: [list]
Test: `[command]`
Commit: `migration(<target>): batch 1 — [description]`
Rollback: `git reset --hard HEAD~1`
### Batch 2 — [description]
...
```
============================================================
PHASE 3: EXECUTION
============================================================
Execute each batch sequentially. For each batch:
1. APPLY CHANGES
- Edit each file per the plan
- Apply changes mechanically — do not refactor or improve unrelated code
- If a file differs significantly from the plan (unexpected complexity),
HALT the batch and report before continuing
2. VERIFY THE BATCH
- Run the test command specified in the plan
- If tests pass: commit the batch and proceed to the next
- If tests fail:
a. Diagnose the failure (max 3 diagnosis attempts)
b. Fix only the failing test's direct cause — no scope creep
c. Re-run tests
d. If still failing after 3 attempts: HALT and report the blocker
3. COMMIT DISCIPLINE
- One commit per batch
- Commit message format: `migration(<target>): batch N — <description>`
- Never commit a failing test suite
4. BLOCKER ESCALATION FORMAT
If halting, output:
```
## MIGRATION HALTED — Batch N
Blocker: [description]
File: [path:line]
Attempts: [N]
Test output: [relevant excerpt]
Recommended action: [specific next step for human]
Completed batches: [N] of [total]
Safe rollback: `git reset --hard <commit-sha>`
```
============================================================
PHASE 4: CROSS-CODEBASE VALIDATION
============================================================
After all batches complete, reload the entire migrated codebase
into context for a final consistency pass.
1. CONSISTENCY CHECKS
- Verify no files in the impact map were missed
- Check for inconsistencies introduced across batch boundaries
(e.g., mixed old/new patterns in the same module group)
- Verify all exports/imports resolve correctly
- Check for any accidental regressions (patterns that should
have changed but weren't touched by any batch)
2. TEST SUITE
- Run the full test suite: `pnpm test` (or project equivalent)
- Run the build: `pnpm build` (or project equivalent)
- If either fails: diagnose and fix before reporting success
3. FINAL REPORT
```
## Migration Complete — <target>
### Summary
- Batches executed: N of N
- Files changed: N
- Files unchanged: N
- Test suite: PASS / FAIL (with details if FAIL)
- Build: PASS / FAIL
### Consistency findings
- Missed files: [list or "none"]
- Cross-batch inconsistencies: [list or "none"]
- Accidental regressions: [list or "none"]
### Recommended follow-ups
- [any items flagged UNCERTAIN in Phase 1]
- [any manual review items]
- [performance or correctness concerns noted during execution]
```
============================================================
COST OPTIMIZATION NOTES
============================================================
This skill is designed for Fable 5's 1M-token context window.
When using the API directly (not Claude Code):
- Use prompt caching on the static codebase snapshot (Phase 1 + Phase 4)
to achieve ~70% input cost reduction on multi-question sessions
- For non-interactive runs (CI, scheduled audits), use the Batch API
for an additional 50% discount — acceptable for overnight migrations
- Exclude lockfiles, build artifacts, and *.min.* files before loading
context; a pnpm-lock.yaml alone can consume 80–120K tokens on Fable 5
Practical usable envelope in Claude Code: ~830K tokens.
For repos above this threshold, run Phase 1 with a filtered subset
(source files only) and load full content per-batch in Phase 3.
============================================================
SELF-HEALING VALIDATION (max 2 iterations)
============================================================
After producing Phase 1 output, verify:
1. Every file in scope has a classification (not just sampled)
2. The dependency graph is complete (no dangling references)
3. Every batch in Phase 2 has a verifiable test command
If any check fails: re-analyze the deficient section.
After 2 iterations, flag remaining gaps explicitly.