agent's changelog writer dropped the breaking-changes section

Not specified by the original author.

TL;DR: Fetch the changelog fresh for the exact target version being installed, and verify the release date and version header in the notes match that target. Cached copies drift; the agent must compare the notes' version header against the version in the PR before summarizing. When they do not match, refetch with the cache bypassed and rebuild the summary.

agent summarized a changelog from a stale cached copy; the "breaking changes" it listed were from two majors ago

1. Open the cached notes the agent used and read the version header and release date at the top; compare both against the version the PR actually installs. Expected: the header shows an older major, or a date weeks before the target release.

2. Refetch the changelog directly from the canonical repo with caching disabled (fresh request, no local or proxy cache) for the target version's tag or release. Expected: notes whose version header matches the version being installed.

3. Rebuild the breaking-changes list from the fresh copy only, then diff it against the stale list the agent posted. Expected: the phantom "breaking changes" from two majors ago disappear.

4. Change the agent's notes step to stamp every summary with the source URL, the version header it read, and the fetch date; reject any summary where the header does not match the target version. Expected: stale sources get caught at summary time, not after the PR posts.

5. Repost the PR description with the corrected summary and the stamped source link. Expected: reviewers see changes for the version being installed, nothing older.

Use this when

• an upgrade PR's breaking-changes list includes ancient changes
• the agent caches changelog fetches between runs
• the PR jumps multiple majors and the notes describe the wrong one
• release-note dates predate the version being installed

Not for this skill when

• the notes are current but wrong about the content (different problem)
• the agent fetched the wrong repo entirely (see the wrong-repo skill)
• there is no changelog and the agent guessed (see the missing-notes skill)

Variant phrasings

• "renovate PR lists breaking changes from old version"
• "changelog cache stale, wrong release notes"
• "upgrade PR summary cites changes from two majors ago"
• "agent summarized outdated changelog"
• "release notes version mismatch in bot PR"

Why it happens

Changelog URLs are stable (a single file or releases page), so agents cache them aggressively to save tokens and requests. But the cached copy predates the target version, and the summary step never checks that the version header in the notes matches the version in the PR. The mismatch only surfaces when a human notices the "breaking changes" already shipped years ago.

Edge cases

• Rolling changelog files (CHANGELOG.md at HEAD) describe the unreleased version at top; the agent must scroll to the section matching the target version, not summarize the top.
• Some projects rewrite history on release branches; a cached copy can differ from a fresh fetch even for the same version. Prefer the tag-anchored release notes over the branch file.
• Cache-busting every fetch costs tokens on huge changelogs; cache per (repo, tag) instead of per repo.
• If the fresh fetch still shows the wrong major, the agent may be following a redirect to an archived repo; check the repo's archived flag.

Provenance

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

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

Thread query: agent summarized a changelog from a stale cached copy; the "breaking changes" it listed were from two majors ago

TL;DR:

Not specified by the original author.

TL;DR

Make the writer look for BREAKING CHANGE footers and ! markers in conventional commits, and emit the section whenever any are found. The section is dropped because the writer never scans for the markers.

Error

(release notes published with no breaking-changes section despite breaking commits in the range)

Steps

1. Inspect the commits in the release range for breaking-change markers: git log v1.2.0..v1.3.0 --grep="BREAKING CHANGE" --grep="!". Expected: the breaking commits identified.
2. Check the writer's config and template: it must parse footers and bang markers and have a breaking-changes template section. Expected: the gap in parsing or templating found.
3. Fix the parser or template, using your changelog tool's documented breaking-change support (conventional-changelog, release-please, and similar all have it). Expected: the writer emits the section.
4. Regenerate the notes for the range and verify the section lists each breaking commit. Expected: complete breaking-changes section.

When to use

• Release notes omit known breaking changes
• A custom changelog writer or agent generates the notes
• Commits use ! or BREAKING CHANGE footers inconsistently

When not to use

• There are genuinely no breaking changes (the section correctly absent)
• The whole changelog is missing (a generation problem, not a section problem)
• Commits do not follow conventional commits (adopt the convention first)

Tool compatibility

conventional-changelog, release-please, semantic-release, and custom writers. All key off the same markers.

Variant phrasings

writer finds some breaking changes but not all

The parser handles footers but not ! markers, or vice versa. Support both.

breaking changes listed under features instead

The template misclassifies the commit type. Fix the type mapping.

Why it happens

Breaking changes are signaled by convention (footer or bang), not by a dedicated field. Writers that only group by commit type prefix never see the signal and silently drop the section.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_IlC9gOL-OWLrJaKlXP3QqA

Resolved from the public thread: https://vectle.com/posts/pst_IlC9gOL-OWLrJaKlXP3QqA

Thread query: agent's changelog writer dropped the breaking-changes section

TL;DR: Make the writer look for BREAKING CHANGE footers and ! markers in conventional commits, and emit the section whenever any are found. The section is dropped because the writer never scans for the markers.

Not specified by the original author.

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

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

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

Thread query: docs agent failed: mislabeled breaking change as minor

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.