## TL;DR
Check the actual API diff before the agent assigns a version bump. The agent looked at commit messages or at the size of the diff, not at whether public signatures changed, so removals and renames shipped as minor.
Fix: diff the public API surface between releases, flag any removal, rename, or signature change as breaking, and require a major bump plus a changelog callout.

## The error
```text
docs agent failed: mislabeled breaking change as minor
```

## Steps
1. Diff the public API between the two releases: compare exported functions, classes, parameters, and config keys. Tools like a TypeScript API extractor, `cargo public-api`, or a simple export list diff work.
   Expected: a list of removed, renamed, and signature-changed symbols.
2. Confirm the break against the published changelog: find the entry the agent wrote and its version label.
   Expected: you see the breaking symbol listed under a minor or patch heading.
3. Correct the record: bump to the next major version (or mark the release as breaking) and add an explicit BREAKING CHANGE section naming each removed or renamed symbol and its replacement.
   Expected: the changelog states plainly what breaks and how to migrate.
4. Teach the agent the rule: any removal, rename, required-parameter addition, default change, or return-type change in the public API is breaking, regardless of what the commit message says.
   Expected: the agent's version-labeling step consumes the API diff, not just commit text.
5. Add a CI check that fails the release when the API diff shows breaking changes but the planned bump is minor or patch.
   Expected: mislabeled releases are blocked before publishing.

## Use this when
- users report breakage after upgrading a minor or patch release
- the changelog labels a release minor but the API surface shrank or changed
- the agent assigns version bumps from commit messages alone

## Not for this skill when
- the version is right but the changelog text is vague (a writing issue)
- the break came from behavior change with identical signatures (harder; needs behavioral diffing)
- you are deciding initial 0.x versioning policy (a policy question)

## Variant phrasings
- breaking change shipped as minor release
- agent labeled API removal as non-breaking
- semver mislabeled by docs agent
- changelog says minor but clients break on upgrade

## Why it happens
The agent classifies by proxy signals: commit message wording, diff size, or the author's own label. None of those reliably indicate compatibility. Only the public API diff tells the truth, and the agent never computed it.

## Edge cases
- Deprecations are not breaks: marking something deprecated is minor; removing it later is major.
- Config key renames and default value changes count as breaking even though no function signature changed.
- 0.x versions: breaking changes may go in minor bumps by convention, but the changelog must still call them out explicitly.

## Provenance

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