docs(release): classify branch-diff false positives

[szegedi]

Why

branch-diff matches commits, not content, so it reports commits whose changes are already on v5.x. For the v5.18.0 release it listed 37 commits, of which 24 were false positives — nearly two thirds.

The skill previously offered only "skip commits that would result in empty cherry-picks", which gives no way to distinguish those from real ones short of attempting each cherry-pick.

What changed

Three classes of false positive are now documented, all observed while preparing #394:

a. Squash-merged releases. 5.14.2, 5.14.3 and 5.14.4 were squash-merged rather than rebased, so every commit they contained lost its identity and is reported forever. Enumerated per release (from proposals #331, #334, #337) — 18 PRs. A closed set that will not grow.

b. Superseded dependency bumps. A Dependabot bump that never landed on v5.x, which later took an equal-or-newer version of the same package directly. @types/node is the clearest case: the bump targets 25.9.2 while v5.x is already at 26.1.1, so cherry-picking it would downgrade the branch. Recurring, so described as a pattern to recognise rather than a fixed list.

c. The main-only version bump. #154 moved main to 6.0.0-pre and must never reach a 5.x branch.

Applying these rules mechanically to branch-diff v5.x main yields exactly the 13 commits in the v5.18.0 proposal — no residue in either direction.

The verification step

A git diff --stat main check is now required before the version bump, with minimal divergence as the goal.

This one earned its place. While preparing #394 I initially used an age-based cutoff to separate false positives, which looked reasonable and was wrong: it dismissed #352 (grouped Dependabot updates), a genuinely unapplied commit. The content diff is what exposed it. The skill now states that age alone is not evidence and cites #352 as the counterexample.

Smaller fixes

Each from something that actively misled during v5.18.0:

• Pull both branches first — comparing stale refs silently yields a wrong list.
• Parse PR numbers from the trailing URL, not (#NNN). The latter false-matches PR references appearing in commit titles (e.g. "Follow up on fix(otel-thread-ctx): don't derive CtxWrap from node::ObjectWrap #388 review comments").
• Clear the previous release's worktree, which still occupies the path.
• Keep the version commit last; drop and re-create it if a late cherry-pick is needed.

Review note

The class-(a) table encodes claims about release history worth a second pair of eyes. I derived it from the bodies of proposals #331, #334 and #337.

[github-actions]

Overall package size

Self size: 2.49 MB
Deduped: 3.2 MB
No deduping: 3.2 MB

Dependency sizes

| name | version | self size | total size | |------|---------|-----------|------------| | pprof-format | 2.3.1 | 504.33 kB | 504.33 kB | | source-map | 0.8.0 | 185.66 kB | 185.66 kB | | node-gyp-build | 4.8.4 | 13.86 kB | 13.86 kB |

_{🤖 This report was automatically generated by heaviest-objects-in-the-universe}