Codebase Migration

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