Migration Guide

---
name: migration-guide
description: Turn a breaking change (an API rename, removed flag, changed default, or moved module) into concrete upgrade steps with before/after examples. Use when the user asks how to migrate, upgrade, or adapt to a breaking change.
---

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