review-migration

/review-migration

You are validating a completed migration: Check for correctness, residual patterns, and overall quality.

---

Input

The user will specify:

$ARGUMENTS

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

1. Old pattern — What was migrated from?
2. New pattern — What was migrated to?
3. Scope — Directory or glob to check (default: entire project)

---

Step 1 — Check for residual old patterns

Run the bundled residual-check script:

bash ${CLAUDE_SKILL_DIR}/scripts/check-residual-patterns.sh "<old-pattern>" "<scope>" "<ext>"

If the script is not available, fall back to:

grep -rn "<old-pattern>" --include="*.<ext>" <scope>/

Report:

Residual Pattern Check
══════════════════════
  Old imports found:   N files
  Old API usage found: N occurrences

If residuals found, list each file and line number.

---

Step 2 — Run the full test suite

# Use the project's test command

Report:

Test Suite
══════════
  Total:   N tests
  Passed:  N ✓
  Failed:  N ✗
  Skipped: N

---

Step 3 — Verify build

# Use the project's build command

Report:

Build
═════
  Status:   ✓ successful (or ✗ failed)
  Warnings: N
  Errors:   N

---

Step 4 — Diff summary

Analyze the git diff:

git diff --stat
git diff --name-only

Group changes by type:

Changes Summary
═══════════════
  Import changes:     N files
  API usage changes:  N files
  Type changes:       N files
  Test updates:       N files
  Config changes:     N files
  New files:          N files
  Deleted files:      N files

---

Step 5 — Quality assessment

Quality Assessment
══════════════════
  ✓ No residual old patterns
  ✓ All tests passing
  ✓ Build successful
  ✓ Consistent naming conventions
  ✓ No TODO/FIXME related to migration left behind
  ✓ No commented-out old code (deleted, not commented)
  ✗ [Any issues found]

---

Final Report

Migration Review: [old] → [new]
═══════════════════════════════════════
  Status:          ✓ PASS (or ✗ NEEDS ATTENTION)

  Residual check:  ✓ 0 old patterns found
  Tests:           ✓ N/N passing
  Build:           ✓ clean
  Files changed:   N

  Issues found:    N
  [list any issues]

  Recommendation:  Ready to ship (or: Fix N issues first)

---

Gotchas

These are common failure modes when validating migrations. Watch for them:

• Checking only the exact old pattern. The migration used OldClass but aliased imports, dynamic references, string literals, and comments may use variations. Cast a wider net in the residual check.
• Ignoring test coverage gaps. All tests pass, but the tests never exercised the migrated code paths. Check that tests actually cover the new pattern, not just that they don't fail.
• Declaring clean too early. Build passes and tests pass, but runtime behavior differs. If the project has integration or E2E tests, run those too — unit tests alone may miss behavioral regressions.
• Missing re-exports and barrel files. A file was migrated but the barrel file (index.ts, __init__.py, etc.) still re-exports the old name. These often slip through grep because the barrel references the module, not the pattern directly.
• Not checking generated files. Config files, lockfiles, or auto-generated code may still reference the old pattern and won't be caught by source-only grep.

---

What to do with issues

• Residual patterns: Run /migrate targeting only the files with residuals
• Test failures: Investigate if migration-related or pre-existing
• Build errors: Usually missing imports or type mismatches — fix inline