migrate

name	migrate
description	Automates batch file migrations from one pattern to another. Language and framework agnostic. Use when user says "migrate files", "batch migration", "convert all files from X to Y", "replace pattern across files", "mass refactor", or "migrate codebase". Do NOT use for single-file changes or non-migration refactors.
argument-hint	[source pattern → target pattern]
allowed-tools	Read, Glob, Grep, Bash, Edit, Write
metadata	{"author":"roberto-ramirez","version":"1.0.0","category":"workflow-automation","tags":["migration","batch","refactor","codebase"]}

/migrate

You are executing a batch migration: Transform multiple files from one pattern to another systematically.

---

Input

The user will specify:

$ARGUMENTS

If $ARGUMENTS is empty, ask the user to provide:

1. Source pattern — What are we migrating from? (e.g., old import, deprecated API, legacy syntax)
2. Target pattern — What are we migrating to? (e.g., new import, replacement API, modern syntax)
3. Scope — Which directory or file glob to scan? (default: entire project)

---

Step 1 — Scan for files matching the source pattern

Identify all files containing the source pattern. Run the bundled scan script:

bash ${CLAUDE_SKILL_DIR}/scripts/scan-pattern.sh "<source-pattern>" "<scope>" "<ext>"

If the script is not available, fall back to:

grep -rl "<source-pattern>" --include="*.<ext>" <scope>/

Report findings:

Found N files matching source pattern:
  1. path/to/FileA.ext (N occurrences)
  2. path/to/FileB.ext (N occurrences)
  ...

If zero files found, report and stop.

---

Step 2 — Analyze dependencies and ordering

Order files by dependency graph:

1. Shared utilities / base classes — migrated first (others depend on them)
2. Intermediate modules — migrated next
3. Leaf files — migrated last (no dependents)

Present the migration order to the user.

---

Step 3 — Create task list

Create a list tracking every file to migrate. Present to the user for approval before proceeding.

---

Step 4 — Migrate file by file

For each file in priority order:

4a. Read the file

Read the entire file. Understand its structure, imports, and usage of the source pattern.

4b. Transform

Apply the migration:

• Replace imports / includes / requires
• Update API usage (function signatures, parameters, return types)
• Adapt to new patterns
• Preserve existing behavior — migration is a refactor, not a feature change

4c. Verify — no residual old patterns

grep -n "<source-pattern>" <migrated-file>

If any matches remain, fix them.

4d. Run tests for the affected module

# Use the project's test command targeting the affected file/module

If tests fail:

1. Read the error
2. Determine if failure is migration-related or pre-existing
3. Fix migration-related failures
4. Re-run until green

4e. Mark complete, move to next file

---

Step 5 — Validate after every batch of 5 files

After every 5 files, run the bundled validation script:

bash ${CLAUDE_SKILL_DIR}/scripts/validate-migration.sh "<old-pattern>" "<scope>" "<ext>"

This runs a residual check, build, and full test suite. If any step fails, stop and fix before continuing.

---

Step 6 — Generate progress report

Migration Report: [source] → [target]
═══════════════════════════════════════
  Total files:     N
  Migrated:        N  ✓
  Failed:          0
  Remaining:       0

  Build:           ✓ passing
  Tests:           ✓ passing (N tests)

  Residual check:
    grep -r "<source-pattern>" <scope>/ → 0 matches ✓

---

Gotchas

These are common failure modes during batch migrations. Watch for them:

• Find-and-replace mindset. Claude treats migration as a text substitution. But OldClass.method() might be called with different argument patterns in different files. Read each file — the old pattern may be used in subtly different ways that require different transformations.
• Breaking the dependency graph. Migrating a leaf file before the shared utility it depends on means the leaf file references the new pattern but the utility still exports the old one. Always migrate dependencies first.
• Forgetting transitive references. You migrated import { OldName } to import { NewName } but didn't check re-exports, type references, or string literals that reference the old name (e.g., in error messages, logging, or serialization).
• Not committing incrementally. If you migrate 30 files and something breaks at file 25, reverting means losing files 1-24. Commit every 5 files so you can revert a small batch.
• Declaring victory with residual patterns. Running grep for the exact old pattern but missing variations (e.g., aliased imports, dynamic references, comments that document the old API). Cast a wider net in the residual check.

---

Important constraints

• Never skip verification. Every file must be clean of the old pattern before moving on.
• Never batch-transform without reading. Each file may have unique edge cases.
• Preserve behavior. Migrations are refactors, not feature changes.
• Stop on repeated failures. If 3+ consecutive files fail the same way, pause and reassess the strategy.
• Commit incrementally. After each batch of 5 files, suggest the user commit progress.
• Language agnostic. This skill works for any language — adapt grep patterns, test commands, and build commands to the project.

---

Next step

After the migration is complete, validate with:

/review-migration