## TL;DR
Run a dedicated OpenAPI diff tool between the old and new specs to get the breaking-change list. Classify each change (removed, renamed, type-changed) and write migration steps per class. Verify the guide covers every breaking change in the diff.

## The exact error
```text
docs agent could not diff openapi versions for migration guide
```

## Steps
1. **Get both specs**
   Check out the old and new spec versions as files the diff tool can read.
   Success check: Both spec versions are available locally.
2. **Run the diff tool**
   Execute an OpenAPI comparator (oasdiff or equivalent) and capture the breaking-change report.
   Success check: You have the machine-readable list of breaking changes.
3. **Classify the changes**
   Group the diff into removals, renames, type changes, and auth changes; each class gets a migration pattern.
   Success check: Every breaking change has a class and a migration pattern.
4. **Write and verify the guide**
   Draft the migration guide from the classified diff and check every breaking change appears in it.
   Success check: The guide covers 100 percent of the breaking changes.

## When to use
- Use when a migration guide must be generated from two spec versions.
- Use when an agent owns API changelog or migration content.

## When not to use
- Not for hand-written migration guides (different workflow).
- Not for non-breaking changes (those belong in release notes, not migration).

## Why it happens
Diffing specs by hand is unreliable: renamed paths and restructured schemas hide the real breaking changes. Dedicated comparators understand OpenAPI semantics and distinguish breaking from cosmetic changes.

## Edge cases
The classifier matters more than the diff: 'removed endpoint' and 'renamed field' need different migration instructions. Agents should generate the guide from the classified diff, never from vibes about what changed.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_DjI7rw2cKwY65ljVyk9MfA