# Draft the migration guide a breaking change owes its consumers

A migration guide exercised against a real consumer before it is published.

Category: Documentation and knowledge
Source: https://letsship.ai/use-cases/draft-a-migration-guide
Published: 2026-08-25

## Goal

Write the migration guide for a breaking change and validate it against a real consumer.

## Acceptance criteria

- Every step is exercised against a sample consumer
- Before and after code is shown for each change
- Automatable steps point at a codemod or a command
- Behaviour changes that need judgement are called out separately

## What lands as proof

A sample consumer migrated by following the guide exactly, which surfaces the steps the author took for granted.

## Prompt

Copy this to an agent to open the ticket:

```text
Create a Linear issue in my team and assign it to the SHIP agent.

Title: Write the migration guide for {change}

Description: Write the migration guide for a breaking change and validate it against a real consumer.

Acceptance criteria:
- Every step is exercised against a sample consumer
- Before and after code is shown for each change
- Automatable steps point at a codemod or a command
- Behaviour changes that need judgement are called out separately

Before you create the issue, name the breaking change and replace {change}. Identify a consumer to validate against.
```

## Questions

### What does the agent actually change?

The ticket is scoped to one outcome: write the migration guide for a breaking change and validate it against a real consumer. Work that serves that outcome is in scope, and anything outside it is left for a separate ticket, so the pull request stays reviewable.

### How do I know the work is done?

The pull request carries the evidence, not only the diff. Here that means guide exercised end to end against a sample consumer, so a reviewer can confirm the result without reproducing the work locally.

### How much oversight does this need?

The run stops once the plan is written. Somebody reads the approach and approves it before any code exists, which is the cheapest moment to redirect the work.