{"id":"82071f5a-7901-4e4f-80ce-12d85d8a38e1","shortId":"XqCjPA","kind":"skill","title":"migrate","tagline":">-","description":"!../principles/SKILL_BODY.md\n\n!../tool-gitnexus/SKILL_BODY.md\n\n---\n\n# Migration Workflow\n\n## Core Principle\n\nMigrations 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.**\n\n> **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.\n\n---\n\n## Complete Execution Workflow\n\n> **Progress tracking:** At the start of each step, output an updated progress block so the user knows where the migration stands.\n>\n> ```\n> Migration Progress\n> ✓ Step 1: Scope Scan         — <N files identified, Tier N impact>\n> ✓ Step 2: Compatibility      — <N hard-cutover steps flagged>\n> → Step 3: Migration Plan     — in progress\n> ○ Step 4: Per-Module Migration + Validation\n> ○ Step 5: Cleanup\n> ```\n>\n> Replace `○` with `→` for the current step, and `✓` once complete.\n\n---\n\n### Step 1: Migration Scope Scan\n\nEnumerate all affected files and produce a migration inventory:\n\n- List every file that references the old API, type, pattern, or version\n- Score the total impact using the Impact Radius Scorecard (§3.2)\n- Identify dependency relationships between affected files\n\n```\n─── Migration Inventory ─────────────────────────────\nMigration: <from X> → <to Y>\nImpact radius score: N → <Tier>\n\nFile                   | Change Type             | Dependency Order\n───────────────────────|─────────────────────────|──────────────────────\n<file A>               | <API call → new API>    | leaf (migrate first)\n<file B>               | <type annotation>       | depends on A\n<file C>               | <core module>           | migrate last\n─────────────────────────────────────────────────────\n```\n\n🔗 When GitNexus is available, use `impact` MCP tool to enumerate all dependents automatically.\n\n### Step 2: Compatibility Assessment\n\nFor each breaking change in the migration:\n\n- Is there a **compatibility shim** available (e.g., an adapter, polyfill, or compatibility layer)?\n- What is the **backward compatibility window** — can the old and new API coexist during migration?\n- Is there **runtime coercion risk** — can old data be silently misinterpreted by the new code?\n\n```\n─── Compatibility Assessment ────────────────────────\nBreaking change: <description>\n  Shim available:         Yes (<name / approach>) / No\n  Old/new coexistence:    Yes (window: <duration / version range>) / No\n  Runtime coercion risk:  Yes (describe) / No\n  Rollback approach:      <how to revert this step if it fails>\n─────────────────────────────────────────────────────\n```\n\n**If no shim is available and old/new cannot coexist:** flag as a hard-cutover migration step. Use the confirmation gate with:\n\n- **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?\"`\n- **options**:\n  - `\"Yes, I authorize this hard-cutover step\"`\n  - `\"No — let's find a compatibility shim or defer this step\"`\n\nDo not proceed with this step until the user selects \"Yes\".\n\n### Step 3: Migration Order Planning\n\n**Ordering rule (per §6.2 dependency direction):** migrate leaf modules first, core modules last.\n\n```\n─── Migration Sequence ──────────────────────────────\nPhase 1 (no dependents): <leaf files — safe to migrate first>\nPhase 2 (depend on Phase 1 only): <next tier>\n...\nPhase N (core): <modules with the most dependents — migrate last>\n\nRollback boundary after each phase: if Phase N+1 fails, revert only Phase N.\n─────────────────────────────────────────────────────\n```\n\n**Each phase should be a separate commit** — this preserves rollback granularity and makes the migration history bisectable.\n\n### Confirmation Gate (between Step 3 and Step 4)\n\nAfter completing the Migration Sequence, **before executing any module change**, use the confirmation gate with:\n\n- **question**: The full Migration Sequence block above, plus a summary of any hard-cutover steps identified in Step 2\n- **options**:\n  - `\"Yes, begin execution in this order\"`\n  - `\"No — let's revise the sequence or scope\"`\n\nDo not begin Step 4 until the user selects \"Yes\".\n\n**If user selects \"No\":** ask *\"What should change — the order, scope, or approach?\"*, update the Migration Sequence, and use the confirmation gate again.\n\n---\n\n### Step 4: Per-Module Migration + Validation\n\nFor each module, in the order established in Step 3:\n\n1. Apply the migration to this module only\n2. Run the associated tests for this module (and its direct callers)\n3. **If tests pass:** continue to the next module\n4. **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.\n\n```\n─── Per-Module Migration Log ────────────────────────\nModule: <file / module name>\nChange applied: <description>\nTests run: <test file(s) or test command>\nResult: ✅ Pass — proceed to next module / ❌ Fail — stopped (diagnosis below)\n─────────────────────────────────────────────────────\n```\n\n**Forbidden:** Migrating multiple modules between test runs. Each module migration must be validated before the next begins.\n\n### Step 5: Legacy Code Cleanup\n\nAfter all modules pass validation, remove migration scaffolding in a **separate commit**:\n\n- Delete compatibility shims and adapters\n- Remove old type aliases and version-compatibility branches\n- Remove `@deprecated` annotations added for this migration\n- Remove feature flags introduced to gate the migration\n\n```\n─── Cleanup Checklist ───────────────────────────────\n[ ] Compatibility shims removed\n[ ] Old type aliases / version branches deleted\n[ ] @deprecated annotations cleared\n[ ] Migration feature flags removed\n[ ] Tests updated to remove compatibility-mode paths\n[ ] Documentation updated (README, CHANGELOG, migration guide)\n─────────────────────────────────────────────────────\n```\n\n> **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.\n\n---\n\n## Forbidden Actions\n\n- Do not migrate multiple modules in a single step without validating each — this removes rollback granularity\n- Do not delete the old API or shim before all consumers have been migrated and tested\n- Do not make behavioral changes alongside migration changes — migration commits must be pure migrations (structure changes only, behavior preserved)\n\n---\n\n## Sprint State Integration\n\nIf `.sextant/state.json` exists in the project root and the current task matches a sprint task:\n\n- **On start:** offer to update the task's `status` from `pending` → `in_progress`. Ask: *\"Update sprint state to mark Task N as in_progress?\"*\n- **On completion** (acceptance condition met): offer to update `status` to `done`. Ask: *\"Update sprint state to mark Task N as done?\"*\n- **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\": \"<one-sentence blocker description>\"}` to the top-level `flags` array. Do not proceed to the next task while a task is blocked.\n\nDo not write the file without explicit user confirmation. If the user declines, continue without state updates.\n\n---\n\n## Reply Format\n\nMigration Summary:\n\n| # | Item | Detail |\n|---|------|--------|\n| [1] | Scope | <N files; impact radius N → Tier; N phases planned> |\n| [2] | Compatibility | <shims available / hard-cutover steps flagged (N require authorization)> |\n| [3] | Sequence | <phase-by-phase plan with rollback boundaries> |\n| [4] | Current status | <Phase N of M: ✅ complete / ❌ stopped at <module> (diagnosis: <root cause>)> |\n| [5] | Needs your input | <hard-cutover steps requiring explicit authorization; test failures to diagnose> |","tags":["migrate","sextant","hellotern","agent-skills","claude-code","skill-md"],"capabilities":["skill","source-hellotern","skill-migrate","topic-agent-skills","topic-claude-code","topic-skill-md"],"categories":["Sextant"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/hellotern/Sextant/migrate","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add hellotern/Sextant","source_repo":"https://github.com/hellotern/Sextant","install_from":"skills.sh"}},"qualityScore":"0.457","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 14 github stars · SKILL.md body (8,135 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-22T13:03:25.927Z","embedding":null,"createdAt":"2026-04-19T00:40:21.496Z","updatedAt":"2026-04-22T13:03:25.927Z","lastSeenAt":"2026-04-22T13:03:25.927Z","tsv":"'+1':431 '/principles/skill_body.md':2 '/tool-gitnexus/skill_body.md':3 '1':102,140,397,411,562,966 '2':112,219,407,496,570,977 '3':115,377,458,561,582,989 '3.2':174 '4':121,461,516,546,591,991 '5':128,661,1002 '6.2':384 'accept':868 'across':57 'action':772 'ad':694 'adapt':237,681 'affect':146,179 'alias':685,713 'alongsid':810 'ambigu':894 'annot':693,718 'api':160,193,196,253,794 'appear':769 'append':920 'appli':563,624 'approach':292,534 'array':930 'ask':526,855,877,902 'assess':221,273,318 'associ':573 'author':343,348,988,1012 'automat':217 'avail':208,234,277,297,980 'backward':245 'begin':499,514,659 'behavior':53,808,822 'bisect':453,765 'block':90,319,482,907,918,942 'blocker':888 'boundari':74,424 'branch':690,715 'break':224,274 'call':194 'caller':581 'cannot':300,334 'caus':612 'chang':49,56,189,225,275,471,529,623,743,756,809,812,820 'changelog':735 'checklist':707 'checkpoint':28 'cleanup':129,664,706,742 'clear':616,719 'code':271,663 'coercion':260,286 'coexist':254,281,301,335 'command':632 'commit':443,676,741,814 'compat':65,113,220,232,240,246,272,317,359,678,689,708,729,978 'compatibility-mod':728 'complet':75,138,463,867,998 'condit':869 'confirm':38,312,454,474,542,915,951 'consum':799 'continu':586,598,956 'coordin':55 'core':6,18,391,415 'current':134,836,992 'cutov':307,329,352,491,983,1008 'data':264 'debug':608 'declin':955 'defer':362 'defin':62 'delet':677,716,791 'depend':23,176,191,200,216,385,399,408,420,892 'deprec':692,717 'describ':289 'detail':965 'diagnos':603,1016 'diagnosi':641,1001 'direct':386,580 'distinct':40 'document':732 'done':876,886 'e.g':235 'easier':759,763 'enumer':144,214 'establish':558 'everi':27,154 'execut':76,344,468,500 'exist':829 'explicit':949,1011 'fail':432,594,639 'failur':605,890,1014 'featur':45,48,699,721 'file':106,147,155,180,188,401,628,947,969 'find':357 'first':199,390,405 'flag':302,700,722,913,929,985 'forbidden':643,771 'format':961 'full':479 'function':754 'gate':313,455,475,543,703 'gitnexus':206 'granular':447,788 'guid':737 'halt':896 'hard':306,328,351,490,982,1007 'hard-cutov':305,327,350,489,981,1006 'histori':452 'identifi':107,175,493 'immedi':615 'impact':110,168,171,184,210,970 'input':1005 'integr':826 'intervent':342 'introduc':701 'inventori':152,182 'irrevers':16 'issu':900 'item':964 'keep':30,750 'know':94 'last':204,393,422 'later':770 'layer':241 'leaf':197,388,400 'legaci':662 'let':355,505 'level':928 'link':606 'list':153 'log':621 'low':746 'low-risk':745 'm':997 'make':449,757,807 'mani':58 'manual':341 'mark':860,882,903 'match':838 'mcp':211 'mechan':749 'met':870 'migrat':1,4,8,21,54,97,99,116,125,141,151,181,183,198,203,228,256,308,378,387,394,404,421,451,465,480,537,550,565,620,644,652,671,697,705,720,736,755,775,802,811,813,818,962 'misinterpret':267 'miss':891 'mode':730 'modifi':44,47 'modify-featur':43,46 'modul':12,36,51,59,124,389,392,416,470,549,554,568,577,590,602,619,622,638,646,651,667,777 'multi':11 'multi-modul':10 'multipl':645,776 'must':653,815 'n':105,109,187,414,430,436,862,884,905,922,968,972,974,986,995 'need':1003 'new':195,252,270,333 'next':589,601,637,658,936 'offer':844,871 'old':159,250,263,331,683,711,793 'old/new':280,299 'one':50 'open':33 'option':32,345,497 'order':24,192,379,381,503,531,557 'output':86 'partial':15 'pass':585,634,668 'path':731 'pattern':162 'pend':852 'per':123,383,548,618 'per-modul':122,547,617 'phase':73,396,406,410,413,427,429,435,438,975,994 'plan':70,117,380,976 'plus':323,484 'point':339 'polyfil':238 'preserv':445,823 'principl':7 'proceed':367,635,933 'produc':149 'progress':78,89,100,119,854,865,897 'project':832 'pure':817 'question':315,477 'radius':172,185,971 'readm':734 'reason':911,923 'record':909 'refer':157 'regress':768 'relationship':177 'remov':670,682,691,698,710,723,727,786 'replac':130 'repli':960 'requir':340,987,1010 'result':633 'revert':433 'review':761 'revis':507 'risk':261,287,747 'rollback':31,69,291,336,423,446,787 'root':611,833 'rule':382 'run':571,626,649 'runtim':259,285 'safe':402 'scaffold':672 'scan':104,143 'scope':103,142,511,532,967 'score':165,186 'scorecard':173 'select':374,520,524 'separ':442,675,740,752 'sequenc':63,395,466,481,509,538,990 'set':916 'sextant':42,607 'sextant/state.json':828 'shim':66,233,276,295,360,679,709,796,979 'silent':266 'singl':780 'skill' 'skill-migrate' 'source-hellotern' 'sprint':824,840,857,879 'stand':98 'start':82,843 'state':13,825,858,880,958 'status':850,874,917,993 'step':85,101,111,114,120,127,135,139,218,309,322,330,353,364,370,376,457,460,492,495,515,545,560,660,781,984,1009 'stop':595,640,999 'strategi':19 'structur':819 'summari':486,963 'surfac':898 'task':837,841,848,861,883,904,921,937,940 'test':574,584,593,625,627,631,648,724,804,889,1013 'tier':108,973 'tool':212 'top':927 'top-level':926 'topic-agent-skills' 'topic-claude-code' 'topic-skill-md' 'total':167 'track':79 'type':161,190,684,712 'unresolv':893 'updat':88,535,725,733,846,856,873,878,959 'use':169,209,310,472,540 'user':93,373,519,523,950,954 'valid':25,126,551,655,669,783 'version':164,688,714 'version-compat':687 'window':247,283 'without':782,948,957 'work':39 'workflow':5,77 'write':945 'yes':278,282,288,346,375,498,521","prices":[{"id":"e92b5e7d-cca2-4bbd-921c-d84e05e9f5be","listingId":"82071f5a-7901-4e4f-80ce-12d85d8a38e1","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"hellotern","category":"Sextant","install_from":"skills.sh"},"createdAt":"2026-04-19T00:40:21.496Z"}],"sources":[{"listingId":"82071f5a-7901-4e4f-80ce-12d85d8a38e1","source":"github","sourceId":"hellotern/Sextant/migrate","sourceUrl":"https://github.com/hellotern/Sextant/tree/main/skills/migrate","isPrimary":false,"firstSeenAt":"2026-04-19T00:40:21.496Z","lastSeenAt":"2026-04-22T13:03:25.927Z"}],"details":{"listingId":"82071f5a-7901-4e4f-80ce-12d85d8a38e1","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"hellotern","slug":"migrate","github":{"repo":"hellotern/Sextant","stars":14,"topics":["agent-skills","claude-code","skill-md"],"license":"mit","html_url":"https://github.com/hellotern/Sextant","pushed_at":"2026-04-07T00:57:27Z","description":"init","skill_md_sha":"fbdc36ed1813a994d2083e8c2ca7a3f1430dbb45","skill_md_path":"skills/migrate/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/hellotern/Sextant/tree/main/skills/migrate"},"layout":"multi","source":"github","category":"Sextant","frontmatter":{"description":">-"},"skills_sh_url":"https://skills.sh/hellotern/Sextant/migrate"},"updatedAt":"2026-04-22T13:03:25.927Z"}}