migration-guide

# migration-guide — write upgrade steps for a breaking change Produce a guide that lets a user on the old version land on the new one with the least friction. ## Pin down what actually broke Identify the precise breaking change before writing a word. Get it from the diff and history, not from the description alone: - `git diff <old>..<new>` on the affected surface, and `gh pr view <n>` for the PR that introduced it. - Dispatch the researcher (`purpose: explore`) to confirm the exact old and new shapes: the old name/signature/default, the new one, and whether a compatibility shim or deprecation window exists. Never document a rename or signature change from memory — the exact symbols are what users will copy. ## Structure # Migrating to <version> ## What changed <one paragraph: the change and why, in user terms> ## Upgrade steps 1. <ordered, mechanical steps> ## Before / after ``` # before ... # after ... ``` ## If you can't upgrade yet <deprecation window, shim, or flag to opt out — if one exists> ## Write the steps - Make each step mechanical and verifiable ("rename `--foo` to `--bar`", not "update your flags"). A user should be able to follow it without rereading the whole guide. - Show a minimal, real before/after for each distinct change. Keep examples copy-pasteable. - State explicitly when there is no automated path and a manual edit is required. ## Verify Route the finished guide through the `reviewer` (`purpose: review`). Migration guides are acted on directly, so a wrong flag name or step is high-cost — the cross-vendor fact-check is worth it here.