Skip to content

release skill: make the two-PR flow, the production smoke, the ledger artifact and the UI-driven tag explicit #2298

Description

@cliffhall

.claude/skills/release/SKILL.md describes a v2 release as "three steps" — audit + bump, merge, tag — and leaves four things that a release actually depends on either implicit or absent. Someone following the skill as written can get every step technically right and still cut the release wrong.

What is missing

  1. That it is two pull requests, and what belongs on each. The skill says the audit and the bump go on v2/main "in the same PR", then that the merge happens "through the usual milestone-merge branch" — but it never states that these are two PRs against two different base branches, that PR 1 must merge before PR 2 is opened (or the merge branch takes a v2/main without the bump), or that PR 2 must stay a pure merge with no commits of its own.
  2. The production smoke of the release candidate. Every contribution closed in the milestone is driven by hand from the production build — the packaged bin and built bundles, not vite dev — in a dedicated worktree with a real npm install. The skill says nothing about this at all, so it reads as though a green local:gate on the merge branch is the whole verification.
  3. The ledger artifact. That smoke is written up as a published artifact the maintainers review before the merge lands, with a per-issue table of what was driven and what was observed. Precedent: the v2.5.0 smoke ledger. Nothing in the skill mentions it, so it depends entirely on whoever cut the last release remembering.
  4. Where a smoke finding gets fixed. It goes on v2/main and reaches the merge branch by re-merging — never as a commit on the merge branch, which would break the byte-identical-tree property that makes the smoke mean anything (Three small cleanups flagged in the v2.2.0 merge review #2000chore: three small cleanups flagged in the v2.2.0 merge review #2092, chore: merge v2/main for the v2.5.0 milestone release #2215v2.5.0 merge review: progress-toast id collisions, and a CSPRNG-capable fallback for newAttemptId #2216–2224). The skill has the bump version of this rule (v2/main's version drifts from main — bump on v2/main before the milestone merge #2010) but not the findings version.
  5. That the tag and Release are normally created through the GitHub UI. The skill gives only the git tag / git push path, which is the fallback in practice.

Proposed change

Restructure the skill around the real shape — PR 1 → PR 2 → Release — with:

  • a "The shape" section up front: a table contrasting the two PRs by branch, base, contents, verification and merge condition, plus why they must not be folded together;
  • step 2 broken into the tree-hash check + production smoke, the ledger's structure, and the fix-on-v2/main rule;
  • step 3 leading with the GitHub UI path, keeping the CLI commands as the by-hand equivalent.

Docs-only; no code or gate changes. The existing npm audit fix, --no-git-tag-version, tag-origin/main, no-v-prefix and #2010 warnings are all preserved.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationv2Issues and PRs for v2

Type

No type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions