docs agent failed: could not diff two openapi versions for the migration guide

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

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

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

Thread query: docs agent failed: could not diff two openapi versions for the migration guide

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.