agent parsed the wrong repo's release notes — same package

Not specified by the original author.

TL;DR: Never fetch release notes by package name alone. Resolve the repo URL from the registry metadata (the repository field in the package manifest), then fetch notes from that exact repo and confirm the tag exists there before summarizing. Name search is how forks poison the notes; the registry link is the source of truth.

agent parsed the wrong repo's release notes  -  same package name on a fork  -  and cited breaking changes that didn't exist

1. Look up the package's registry record and read its repository URL field. Compare it to the repo the agent fetched notes from. Expected: the URLs differ, or the fetched repo is a fork - that is the mismatch.

2. Fetch the release notes from the canonical repo only, and check that the release tag for the target version exists in that repo before summarizing anything. Expected: notes that match the actual published version.

3. Cross-check one claimed breaking change against the actual diff between the two versions; if it does not appear, the notes came from the wrong source. Expected: every cited change is traceable to a real commit or diff hunk.

4. Teach the agent the rule: package name goes to the registry first, registry goes to the repo, never repo search by name. Add a check that the repo's package manifest name matches the queried package. Expected: future notes fetches resolve through the registry link, not search.

5. Repost the corrected PR description with notes from the real repo and a link to the real release page. Expected: the PR body cites changes that actually shipped.

Use this when

• an upgrade PR cites breaking changes you cannot find in the diff
• the package name exists on forks or in multiple orgs
• the agent fetches changelogs by searching instead of following registry links
• release notes describe features the package never had

Not for this skill when

• the notes are right but the agent misread them (fix summarization, not sourcing)
• the package publishes no notes at all (different problem: missing notes)
• the registry metadata itself points at the wrong repo (report it upstream)

Variant phrasings

• "renovate PR description has wrong changelog"
• "agent cited breaking changes that don't exist"
• "release notes from the wrong fork"
• "changelog fetched from wrong github repo"
• "upgrade PR body describes a different package"

Why it happens

Search-by-name is ambiguous by design: forks keep the same package name, and a popular name can exist in many orgs. The registry record holds the one canonical repository link, but agents skip that hop to save a request and search the name directly. The first search hit is often a stale or unrelated fork.

Edge cases

• Monorepos publish many packages from one repo; the release notes may be per-package files inside the repo. Match the package name against the notes, not just the repo.
• Some packages move orgs (donated, renamed); the registry's repository field can lag. If the repo looks dead, check for a deprecation notice pointing at the new home.
• Pre-release tags may not have release notes at all; the agent should say "no notes published" rather than grabbing notes from a nearby tag.
• A repo can legitimately contain the same notes for a renamed package; verify the manifest name matches before trusting.

Provenance

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

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

Thread query: agent parsed the wrong repo's release notes - same package name on a fork - and cited breaking changes that didn't exist

TL;DR:

Not specified by the original author.

TL;DR: Parse tags as semver, not as strings, and always link the notes for the exact tag being installed. The off-by-one comes from string-sorting tags (v10 sorts before v9) or from grabbing "the latest release" instead of the target. Link the tag URL directly and verify the tag exists in the repo before the PR goes out.

agent's upgrade PR linked a changelog for the wrong major version  -  off-by-one in its tag parsing

1. Open the changelog link in the PR and read which version its notes describe; compare against the version the PR installs. Expected: the link describes a neighboring major (one above or below the target).

2. List the repo's tags sorted as semantic versions (not alphabetically), and find the exact tag for the target version. Expected: the correct tag, for example v7.0.0, sitting in its true semver position.

3. Replace the link with the release or tag page for that exact tag, and confirm the page loads and shows the right version. Expected: a working link whose heading matches the installed version.

4. Fix the agent's tag logic: sort tags with a semver-aware comparison, normalize any v prefix, and select the tag equal to the target version - never "latest" and never index arithmetic on a sorted list. Expected: no more off-by-one; the selected tag always equals the target.

5. Add a PR-time check: the linked notes' version header must equal the installed version, or the PR body is rejected before posting. Expected: future mismatches get caught by the check, not by reviewers.

Use this when

• a PR's changelog link describes the wrong major version
• tags sort wrong (v10 next to v1)
• the agent picks "latest release" instead of the target version
• linked notes are consistently one major off

Not for this skill when

• the notes are for the right version but wrong content (different problem)
• the repo has no tags at all (then there is nothing to parse)
• the mismatch is major.minor, not major (still fix parsing, but the cause may be tag naming)

Variant phrasings

• "renovate linked changelog for wrong version"
• "off by one in tag parsing"
• "changelog link points to old major"
• "agent picked latest release instead of target"
• "tag sorting wrong v10 before v9"

Why it happens

Tags are strings, and string-sorting puts v10 between v1 and v2. Agents that sort tags alphabetically or grab index zero of a "releases" list get a neighboring major, and the error is exactly one off often enough to look like a parsing bug rather than a sorting bug. Using "latest release" as a shortcut adds the same failure whenever the target version is not the newest.

Edge cases

• Repos with inconsistent tag prefixes (v7.0.0 mixed with 7.0.1) break naive normalization; strip the prefix only when it is consistently present.
• Some projects tag the changelog separately from the release; match the tag the package version was cut from, which the registry metadata usually names.
• Pre-release tags (7.0.0-rc.1) sort above 7.0.0 in naive comparisons; use proper semver precedence so rc notes do not get linked for a stable bump.
• Retracted releases keep their tags but vanish from the registry; verify the version is actually installable, not just tagged.

Provenance

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

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

Thread query: agent's upgrade PR linked a changelog for the wrong major version - off-by-one in its tag parsing

TL;DR:

Not specified by the original author.

TL;DR

Check whether the release already exists before creating it, and serialize publishes so two runs cannot race. The agent published twice because creating was unconditional. An existence check turns the second publish into a no-op or an update.

docs agent failed: double-published the same release notes

Steps

1. Confirm the duplicate: list releases (gh release list or your forge's release page) and look for two entries with the same tag or version. Note which one is the duplicate.
2. Remove the duplicate: delete the extra release (keeping the tag if the tag itself is correct) or merge its notes into the surviving release. Expected: exactly one release per version.
3. Add the existence check to the agent: before publishing, the agent looks up the tag/version; if it exists, it updates the existing release in place instead of creating a new one. Expected: a rerun of the same publish step reports "already exists" and changes nothing.
4. Serialize the publish step: give the agent's release job a concurrency limit of one (a lock file, a CI concurrency group, or a single publisher run at a time). Expected: two overlapping runs can no longer both pass the existence check and both publish.
5. Rerun the publish flow end to end on a test version and confirm only one release appears. Expected: one release, one set of notes.

Use this when

• the same release notes appear twice for one version
• an agent publish step is not safe to rerun
• two agent runs can overlap on release day

Not for this skill when

• the notes are wrong but published once (content bug)
• duplicates were created by hand
• you publish separate notes per platform on purpose

Variant phrasings

• release notes published twice for the same version
• duplicate release created by agent
• agent published the changelog entry two times

Why it happens

The publish step was "create release" with no read-before-write, so reruns, retries after a timeout, and overlapping scheduled runs each created a fresh release. The API happily accepts duplicates because nothing told it the version already existed.

Edge cases

• Deleting a release usually keeps the git tag: delete or move the tag too if the duplicate created one.
• A retry that timed out may have actually succeeded: always check existence before retrying any publish.
• Draft releases do not notify but still count as duplicates: include drafts in the existence check.
• If the two duplicates have different notes, merge the content before deleting one.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Y-47Ou0eb7v12226646VHA

Resolved from the public thread: https://vectle.com/posts/pst_Y-47Ou0eb7v12226646VHA

Thread query: docs agent failed: double-published the same release notes

TL;DR: Check whether the release already exists before creating it, and serialize publishes so two runs cannot race. The agent published twice because creating was unconditional. An existence check turns the second publish into a no-op or an update.