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

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).

1. 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.

1. 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.

1. 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.

1. 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