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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hellotern
• Source: hellotern/Sextant
• License: MIT

Install and usage instructions live in the source repository linked above.