# Migrate > You MUST use this skill before starting any cross-module migration, upgrade, or technology conversion. Use when multiple files or modules must change in a coordinated sequence — framework upgrades, language conversions, schema migrations, or major API version changes. Stronger signals: "migrate", "upgrade", "convert", "port", "move from X to Y", "upgrade to version N", "switch from X to Y", "schema migration". Use sextant:modify-feature instead when only a single module's behavior is changing without coordinated multi-step rollout. - Skill: `hellotern/migrate` (Agent Skill) - Install (CLI): `npx skillmds@latest add hellotern/migrate` - Raw SKILL.md: https://api.skillmd.com/api/skills/hellotern/migrate/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: hellotern (https://skillmd.com/u/hellotern) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/hellotern/migrate --- !../principles/SKILL_BODY.md !../tool-gitnexus/SKILL_BODY.md --- # Migration Workflow ## Core Principle Migrations are multi-module, stateful, and partially irreversible. The core strategy is **migrate in dependency order, validate at every checkpoint, and keep rollback options open until all modules are confirmed working.** > **Distinct from sextant:modify-feature:** Modify-feature changes one module's behavior. Migration coordinates changes across many modules in a defined sequence, with compatibility shims and a rollback plan at each phase boundary. --- ## Complete Execution Workflow > **Progress tracking:** At the start of each step, output an updated progress block so the user knows where the migration stands. > > ``` > Migration Progress > ✓ Step 1: Scope Scan — > ✓ Step 2: Compatibility — > → Step 3: Migration Plan — in progress > ○ Step 4: Per-Module Migration + Validation > ○ Step 5: Cleanup > ``` > > Replace `○` with `→` for the current step, and `✓` once complete. --- ### Step 1: Migration Scope Scan Enumerate all affected files and produce a migration inventory: - List every file that references the old API, type, pattern, or version - Score the total impact using the Impact Radius Scorecard (§3.2) - Identify dependency relationships between affected files ``` ─── Migration Inventory ───────────────────────────── Migration: → Impact radius score: N → File | Change Type | Dependency Order ───────────────────────|─────────────────────────|────────────────────── | | leaf (migrate first) | | depends on A | | migrate last ───────────────────────────────────────────────────── ``` 🔗 When GitNexus is available, use `impact` MCP tool to enumerate all dependents automatically. ### Step 2: Compatibility Assessment For each breaking change in the migration: - Is there a **compatibility shim** available (e.g., an adapter, polyfill, or compatibility layer)? - What is the **backward compatibility window** — can the old and new API coexist during migration? - Is there **runtime coercion risk** — can old data be silently misinterpreted by the new code? ``` ─── Compatibility Assessment ──────────────────────── Breaking change: Shim available: Yes () / No Old/new coexistence: Yes (window: ) / No Runtime coercion risk: Yes (describe) / No Rollback approach: ───────────────────────────────────────────────────── ``` **If no shim is available and old/new cannot coexist:** flag as a hard-cutover migration step. Use the confirmation gate with: - **question**: The Compatibility Assessment block for this step, plus: `"This is a hard-cutover step — old and new cannot coexist. Rollback after this point requires manual intervention. Authorize execution?"` - **options**: - `"Yes, I authorize this hard-cutover step"` - `"No — let's find a compatibility shim or defer this step"` Do not proceed with this step until the user selects "Yes". ### Step 3: Migration Order Planning **Ordering rule (per §6.2 dependency direction):** migrate leaf modules first, core modules last. ``` ─── Migration Sequence ────────────────────────────── Phase 1 (no dependents): Phase 2 (depend on Phase 1 only): ... Phase N (core): Rollback boundary after each phase: if Phase N+1 fails, revert only Phase N. ───────────────────────────────────────────────────── ``` **Each phase should be a separate commit** — this preserves rollback granularity and makes the migration history bisectable. ### Confirmation Gate (between Step 3 and Step 4) After completing the Migration Sequence, **before executing any module change**, use the confirmation gate with: - **question**: The full Migration Sequence block above, plus a summary of any hard-cutover steps identified in Step 2 - **options**: - `"Yes, begin execution in this order"` - `"No — let's revise the sequence or scope"` Do not begin Step 4 until the user selects "Yes". **If user selects "No":** ask *"What should change — the order, scope, or approach?"*, update the Migration Sequence, and use the confirmation gate again. --- ### Step 4: Per-Module Migration + Validation For each module, in the order established in Step 3: 1. Apply the migration to this module only 2. Run the associated tests for this module (and its direct callers) 3. **If tests pass:** continue to the next module 4. **If tests fail:** stop. Do not continue to the next module. Diagnose the failure — link `sextant:debug` if the root cause is not immediately clear. ``` ─── Per-Module Migration Log ──────────────────────── Module: Change applied: Tests run: Result: ✅ Pass — proceed to next module / ❌ Fail — stopped (diagnosis below) ───────────────────────────────────────────────────── ``` **Forbidden:** Migrating multiple modules between test runs. Each module migration must be validated before the next begins. ### Step 5: Legacy Code Cleanup After all modules pass validation, remove migration scaffolding in a **separate commit**: - Delete compatibility shims and adapters - Remove old type aliases and version-compatibility branches - Remove `@deprecated` annotations added for this migration - Remove feature flags introduced to gate the migration ``` ─── Cleanup Checklist ─────────────────────────────── [ ] Compatibility shims removed [ ] Old type aliases / version branches deleted [ ] @deprecated annotations cleared [ ] Migration feature flags removed [ ] Tests updated to remove compatibility-mode paths [ ] Documentation updated (README, CHANGELOG, migration guide) ───────────────────────────────────────────────────── ``` > **Why a separate commit?** Cleanup changes are low-risk and mechanical. Keeping them separate from functional migration changes makes both easier to review and easier to bisect if a regression appears later. --- ## Forbidden Actions - Do not migrate multiple modules in a single step without validating each — this removes rollback granularity - Do not delete the old API or shim before all consumers have been migrated and tested - Do not make behavioral changes alongside migration changes — migration commits must be pure migrations (structure changes only, behavior preserved) --- ## Sprint State Integration If `.sextant/state.json` exists in the project root and the current task matches a sprint task: - **On start:** offer to update the task's `status` from `pending` → `in_progress`. Ask: *"Update sprint state to mark Task N as in_progress?"* - **On completion** (acceptance condition met): offer to update `status` to `done`. Ask: *"Update sprint state to mark Task N as done?"* - **On blocker** (test failure, missing dependency, unresolvable ambiguity that halts progress): surface the issue, then ask: *"Mark Task N as blocked and record the reason in flags?"* If confirmed, set `status: "blocked"` and append `{"task": N, "reason": ""}` to the top-level `flags` array. Do not proceed to the next task while a task is blocked. Do not write the file without explicit user confirmation. If the user declines, continue without state updates. --- ## Reply Format Migration Summary: | # | Item | Detail | |---|------|--------| | [1] | Scope | | | [2] | Compatibility | | | [3] | Sequence | | | [4] | Current status | (diagnosis: )> | | [5] | Needs your input | |