| name | release-check |
| description | Post-commit gate. Invoke after every commit (right after /flagrare:staleness-audit). Checks whether a release is due, and if so, proposes a semver bump and a value-focused CHANGELOG entry modeled on Valve's Dota 2 patch notes, describing what the user gains, never what was refactored. Acts on approval. |
Release check
No em-dashes. Nothing this skill writes may contain an em-dash; use a comma, colon, or parentheses instead. Enforced by a repo hook that flags em-dashes in generated .md. See /flagrare:write-docs.
When to invoke
After every commit, immediately after /flagrare:staleness-audit. Cheap to run when there's nothing to do (early-exit ~1 second).
Also invoke on demand whenever the user asks "is a release due?", "let's ship this", "what would v0.2 look like?", or similar.
Procedure
1. Detect the project's release mechanism
Before reading inputs, identify how this project tracks and ships releases:
| Signal | Mechanism |
|---|
.changeset/ directory present | Changesets (pnpm/npm/yarn changeset) |
changelog.d/ directory present | towncrier |
CHANGELOG.md with structured entries | Manual CHANGELOG |
| Conventional commits without a changelog file | Commit-driven: the git log is the changelog |
RELEASES.md or HISTORY.md | Manual release notes |
Note which mechanism applies, the rest of the procedure adapts accordingly.
2. Read inputs
- Version manifest: the file that holds the current version:
- Node.js:
package.json → version, private, name
- Rust:
Cargo.toml → [package] version
- Python:
pyproject.toml → [project] version or __version__ in __init__.py
- Other: identify the canonical version source
- Pending change entries: depends on mechanism detected above:
- Changesets:
.changeset/*.md (excluding README.md and config.json)
- towncrier:
changelog.d/*.{bugfix,feature,breaking,...}
- Manual: inspect
CHANGELOG.md for an [Unreleased] section
- Commit-driven: commits since the last tag (
git log <last-tag>..HEAD)
- Previous releases:
CHANGELOG.md or git tag --sort=-version:refname for stylistic continuity.
3. Compute pending bump
Aggregate pending changes by severity:
- Any breaking/major → proposed bump is major
- Else any new feature/minor → proposed bump is minor
- Else any fix/patch → proposed bump is patch
- Else → nothing pending, release is not due
For Changesets, read the frontmatter level field:
---
"<package-name>": minor
---
Compute the proposed version by applying the bump. Semver pre-1.0 rule: in 0.x.y, breaking changes ride the x (minor) bump, they do not require a major bump.
4. Decide: is the release DUE?
| State | Decision |
|---|
| No pending changes | Not due: done, early exit |
Pending + pre-release / private + proposed version still in 0.0.x range | Not due yet: pre-feature; surface the proposal as a heads-up |
Pending + pre-release / private + proposed version is 0.1.0+ | Due if the headline feature is in: present the proposal, ask the user |
Pending + public package + any major | Due now |
Pending + public package + ≥ 1 minor or ≥ 3 patch | Due: propose to ship |
Pending + public package + < 3 patch only | Soft due: propose but flag it could wait |
These are heuristics. A single security-fix patch ships immediately; ten cosmetic patches probably batch.
5. If DUE, draft the value-focused CHANGELOG entry
This is the part that takes care. Tooling-generated output inherits the raw change-entry text directly, it is often terse and leans technical. Rewrite it before commit.
The model is Valve's Dota 2 patch notes as actually published. The reader is the consumer of the package, not its author. They want: "what can I do now that I couldn't before, and how does my code need to change?"
Style
Section headers, Title Case. Examples from Valve: "General Mechanics", "Hero Adjustments", "Bug Fixes". Adapt to your package:
## General, top-level capabilities and breaking changes## Public API, new exports, signature changes, deprecations## Behaviour, things that work differently without an API change## Performance, measurable wins the user will notice## Bug Fixes, terminal section, purely factual
Skip a section entirely if it has nothing in it.
Per-entry shape, bold anchor + colon + delta. Valve's canonical pattern:
- **Bloodstone**: spell lifesteal 30% → 20%.
- **Anti-Mage**: major rework, new innate applies movement-speed slow.
For a library, the anchor is the symbol the user calls:
- **`Session.run()`**: now returns a frozen `Transcript` instead of
a plain object. `turns` and `finalScene` are where they were.
- **`RangeError`**: carries `.attempted` and `.available` for typed
handling without parsing `.message`.
Use → for numerical or behavioural deltas. "Cooldown 7s → 18s", "Coverage threshold 80% → 75%".
Tense, declarative, present, sentence fragments. "Sessions now expose …" not "Added event emission …".
What goes in:
- Concrete user-callable changes (new exports, behaviour shifts, error-shape changes)
- Numerical deltas with
→
- Breaking changes with a one-line migration hint when non-obvious
- Bug fixes the user might have hit (terminal
## Bug Fixes section, factual)
What stays out:
- Internal refactors that don't change behaviour
- Build/lockfile/lint config changes
- Test framework migrations
- PR numbers, SHAs, branch names
- The why, unless it's a security fix or a breaking-change rationale the user needs
Good vs bad
✅ Value-focused (what the user reads):
## 0.2.0: YYYY-MM-DD
One-line summary of what this release unlocks.
### Public API
- **`Client.query()`**: now accepts an optional `timeout` parameter;
defaults to 30s (was infinite). Pass `timeout: 0` to restore
previous behaviour.
- **`AuthError`**: carries `.statusCode` and `.retryAfter` for
typed handling without parsing `.message`.
### Bug Fixes
- Fixed a race condition in the connection pool that could cause
duplicate requests under high concurrency.
❌ Engineering changelog (what tooling generates verbatim, do NOT ship):
## 0.2.0
- Added timeout parameter to query method
- Refactored AuthError to carry statusCode field
- Fixed race condition (see PR #142)
- Bumped eslint peer range
- Migrated tests from mocha to vitest
6. Sync version-referencing files
A release bump touches more than the version manifest. Several files in a typical repo cite the current version, and they go stale the moment you tag the new one. Sweep for drift before presenting the proposal.
6a. Identify every file the build tooling reads for the version
This is the load-bearing sub-check on multi-build-system projects, and the one that has historically caused the most painful silent failures. A "canonical manifest" mental model is wrong for any project where two build systems each read their own manifest. Each tool stamps the version from a different file into a different artifact, and the artifact whose filename gets uploaded to the registry is what determines whether the publish succeeds.
| Project shape | Files the publish tool reads the version from | Failure mode if they disagree |
|---|
| Rust crate + Python wheel via maturin / PyO3 | Cargo.toml (for cargo publish) and pyproject.toml [project] version (for the wheel filename, maturin uses this, NOT Cargo.toml) | wheel uploads as pkg-OLD-*.whl, PyPI returns 400 File-already-exists, workflow goes red, downstream pip install pkg==NEW returns "no matching distribution" |
| Rust crate + Python wheel via setuptools-rust | Cargo.toml, setup.cfg / setup.py version= | same shape, Python tooling reads its own file |
| Node package with native code (NAPI-RS, neon, node-gyp) | package.json version, native sub-crate Cargo.toml, sometimes binding.gyp | npm publish carries package.json version; native artifact name carries the sub-crate version; mismatch causes load-time failures, not registry rejection |
| Python package + C extension built with scikit-build-core | pyproject.toml [project] version, CMakeLists.txt project(... VERSION ...) | sdist contains conflicting metadata; wheel name vs __version__ divergence |
| Multi-module monorepo (Lerna, pnpm workspaces, Nx) | each module's package.json, plus the root lerna.json / pnpm-workspace.yaml if pinned | partial publish, some modules go out, others don't, dependency resolution breaks for consumers |
For each build system in the project, list every file it reads for the version, and verify they all carry the same value before tagging. The cost is a single grep:
NEW="0.7.2"
grep -nE "^version\s*=" Cargo.toml pyproject.toml setup.cfg package.json 2>/dev/null
If even one file lags, the bump is incomplete. Stop and fix before tagging, recovery from a half-bumped tag is force-pushing the tag, which is real history rewrite.
6b. Other files that cite the current version
| File | What to update | Pattern |
|---|
CITATION.cff | version: field, optionally date-released: | Must match new package version exactly. GitHub's "Cite this repository" button reads this. |
SECURITY.md | Supported-versions table | Bump the supported row; remove rows now out of support. |
README.md | Any "Current version: vX.Y.Z" line; any status framing tied to the version (e.g. "vX.Y.Z is a research-grade preview") | Update version number; reconsider status framing if maturity actually shifted. |
CONTRIBUTING.md, guides, architecture docs | Any "v0.X onwards" or "as of v0.X" claim that's now older than current | Bump or convert to a historical reference. |
| Per-crate / per-module manifests not inheriting from workspace | version = field | Match. (Workspace-inheriting manifests with version.workspace = true need no edit.) |
docs/positioning/*.md, docs/research-log.md | Any "Status: vX" line | Bump if it's meant to track current. |
How to find drift mechanically:
OLD="0.7.0"
grep -rn "v${OLD}\|version.*${OLD}\|\"${OLD}\"" \
--include="*.md" --include="*.cff" --include="*.toml" \
--include="*.yml" --include="*.yaml" \
--exclude-dir=target --exclude-dir=node_modules --exclude-dir=.venv .
For each hit, judge:
- Historical reference ("v0.7.0 introduced X", "added in v0.7.0", "retracted in v0.5"), leave alone. These document what shipped, when. Bumping them rewrites history.
- Current-version claim ("TardigradeDB v0.7.0 is a research-grade preview", "Supported: 0.7.x",
version: "0.7.0" in CITATION.cff), update. These should track HEAD.
Community Standards files deserve special attention since they're the project's public face beyond the README:
CITATION.cff, always bump.SECURITY.md, bump supported versions; if a previously-supported minor falls out of support, surface it in the CHANGELOG entry (consumers on the old minor need to know).CODE_OF_CONDUCT.md, usually no version coupling; verify the contact route is still valid.- Any new community files added since the last release, call them out in the CHANGELOG entry as
### Community Standards.
Include the doc updates in the same release commit. A two-commit release ("bump version" + "update docs") splits the artifact across two SHAs and makes git blame on CITATION.cff lag the actual release date.
Skip this step only for trivial patch releases (e.g. a single typo fix) where the only version-coupled file is the manifest. Anything user-visible, and any release of meaningful scope, gets the full sweep.
7. Present the proposal
Release check: DUE / NOT DUE / SOFT-DUE
Current version: x.y.z → Proposed: x.y.z
Pending changes (N):
- <entry> <level> <one-line summary>
Proposed CHANGELOG entry:
[draft here]
Documentation drift to fix in the same commit (from step 6):
- <file>:<line> <one-line description>
- …
Action plan:
1. Run the project's version-bump command:
Changesets: pnpm changeset version (or npx changeset version)
towncrier: towncrier build --version x.y.z
Manual: edit version manifest + CHANGELOG.md directly
2. Overwrite the generated CHANGELOG entry with the rewrite above.
3. Apply the documentation drift fixes from step 6 (CITATION.cff,
SECURITY.md supported-versions, README status line, etc.).
4. Run the project's verification gate (tests, lint, build).
5. Commit with message matching the project's convention (e.g. "🔖 release: vX.Y.Z").
6. Tag the release commit explicitly (NOT main), using an
**annotated** tag so `--follow-tags` will push it:
git tag -a vX.Y.Z -m "release vX.Y.Z" <release-commit-sha>
The tag MUST point at the commit that bumped the version manifest.
If you tag main and main has moved past the release commit, the
publish workflow will check out the wrong tree and build wheels
with the previous version, PyPI / crates.io will then reject
them as duplicates. (See the "GitHub Release vs tag commit"
section below for why this matters.)
Why annotated, not lightweight: `git push --follow-tags` only
pushes annotated tags (created with `-a` or `-s`). Lightweight
tags (`git tag vX.Y.Z <sha>` with no `-a`) are silently skipped
by `--follow-tags`, and you have to remember to push them
explicitly with `git push origin vX.Y.Z`. Annotated tags also
carry the tagger identity, date, and message, which is what
"this is a release" semantically means, and what `gh release`
and `git describe` expect.
7. Push: git push origin <main-branch> --follow-tags
Verify the tag actually landed on the remote, `--follow-tags`
is a silent no-op for lightweight tags, so don't assume:
git ls-remote --tags origin | grep vX.Y.Z
8. **Create a GitHub Release.** A tag without a release is invisible
to users who watch the repo's Releases page, and workflows
triggered by `on: release: [published]` won't fire.
gh release create vX.Y.Z --title "vX.Y.Z" --notes "<CHANGELOG entry for this version>"
Use the value-focused CHANGELOG entry as the release notes body.
If the project has release-note conventions (e.g. linking to a
full changelog diff), follow them.
9. If the project has a publish workflow (npm publish, cargo publish, PyPI, CI release action),
trigger it, or note that it runs automatically on tag push or
release publish.
10. **Verify the publish actually succeeded.** Tagging is not shipping.
For GitHub Actions release workflows:
gh run list --workflow=<publish-workflow>.yml --limit 1
If status is `failure` or `cancelled`, inspect with `gh run view
<id> --log-failed` and surface the root cause before declaring
the release done. Common failure: wheel filename version doesn't
match the tag (see "GitHub Release vs tag commit" below).
11. **Confirm the artifact actually landed in the index.** Tooling
can succeed-then-silently-skip. For PyPI:
curl -s https://pypi.org/pypi/<package>/json | jq -r .info.version
For crates.io:
cargo search <crate> --limit 1
For npm:
npm view <pkg> version
If the latest published version is still the previous one after
the workflow reports success, something between the workflow and
the registry broke, escalate, don't move on.
[Collect the decision via AskUserQuestion, see "Close with a tool" below. Do not type a prose question here.]
Close with a tool, not prose. Do NOT end the proposal with a prose "Approve to proceed?" and wait, a substantial proposal reads as "turn complete," and a trailing prose question frequently ends the turn with no answer captured (the same stall pattern documented in docs/research/2026-06-11-claude-code-goal-anti-stall.md). Issue an AskUserQuestion tool call with these options:
- Proceed with release (Recommended), execute the action plan (bump, changelog rewrite, doc-drift fixes, commit, annotated tag, push, GitHub Release, verify publish).
- Adjust the changelog: revise the entry, then re-present.
- Adjust the version: change the proposed bump level, then re-present.
- Stop here: leave the proposal for later; make no changes.
GitHub Release vs tag commit: the silent-publish-failure trap
GitHub Actions workflows triggered by on: release: [published] check
out the release's target commit, not the git tag's commit.
These can diverge in three common ways:
- Release created from a stale main. Operator clicks "Draft a new
release" in the GitHub UI, picks tag
vX.Y.Z, but the release's
"target" defaults to main, which may be ahead of (or behind) the
tagged commit. The workflow checks out main, not the tag.
- Tag pushed before version bump. Operator runs
git tag vX.Y.Z
on a commit that doesn't bump the version manifest, then bumps it
in a follow-up commit. The tag is wrong; the workflow builds the
pre-bump tree.
- Multiple consecutive releases without main rebasing. Operator
tags v0.6.0 and v0.7.0 within minutes on commits that all share a
stale Cargo.toml because the version-bump commits haven't been
reordered correctly.
All three produce the same downstream failure: the wheel/crate/package
filename carries the old version, the registry rejects it as a
duplicate of the previously-shipped release, and the workflow status
turns red. Recovery requires either re-tagging (if the registry hasn't
seen any artifact yet) or bumping past the gap (if a partial upload
landed first).
Prevention checklist before pushing the tag:
If the project has had a publish failure of this shape before, surface
it in the release proposal as a known-risk reminder: "v0.7.0 / v0.6.0
both failed PyPI publish due to GitHub-Release-vs-tag-commit drift;
verifying tag commit matches release target before push."
If NOT DUE:
Release check: not due. <one-line reason>.
Pending: N change entries, would propose vX.Y.Z when ready.
8. On approval, execute the plan
Run the steps in order. After each, verify the previous step succeeded. If the version-bump command fails or produces unexpected output, stop and surface, do not silently push.
For the CHANGELOG rewrite specifically:
- Capture the auto-generated entry as a reference (do not ship it).
- Replace that block with the value-focused rewrite.
- Run the project's verification gate.
- Stage and commit.
- Tag the release commit explicitly with an annotated tag
(
git tag -a vX.Y.Z -m "release vX.Y.Z" <release-sha>), not
whatever HEAD happens to be, see "GitHub Release vs tag commit"
in step 7. Use -a so --follow-tags will actually push it;
lightweight tags are silently skipped.
- Push with
--follow-tags, then verify the tag landed:
git ls-remote --tags origin | grep vX.Y.Z.
- Create a GitHub Release (
gh release create vX.Y.Z --title "vX.Y.Z" --notes "<changelog entry>"). A pushed tag without a release is
invisible on the Releases page and won't trigger on: release
workflows.
- Verify the publish workflow succeeded (
gh run list --workflow=<…> --limit 1) and that the artifact landed in the registry (PyPI /
crates.io / npm) before declaring done. A green tag-push is not a
green release.
Anti-patterns
- Don't release just because change entries exist. A single typo-fix for a private package isn't a release event.
- Don't write the changelog from the diff. Write from intent, read the change entries and commit bodies, then translate to what the user gains.
- Don't ship the auto-generated CHANGELOG without rewriting. Tooling output is a starting point, not a final product.
- Don't bypass the user's approval for the actual release. Propose, wait, then act. Releases are public and hard to reverse.
- Don't add a section that's empty. Skip
## Bug Fixes if there are no fixes.
- Don't declare a release done at the tag push. Tagging is necessary, not sufficient. Create the GitHub Release, verify the publish workflow ran green, AND confirm the artifact actually appears in the registry. A "tag pushed, must be live" assumption is how multi-release publish failures stack up unnoticed, the only signal that something's wrong is when a downstream consumer reports
pip install <name> returns the version-before-last.
- Don't skip the GitHub Release. A pushed tag without a corresponding GitHub Release is invisible on the repo's Releases page and won't trigger
on: release: [published] workflows. Always create it via gh release create.
- Don't assume one manifest is the only version source. On multi-build-system projects (maturin/PyO3, setuptools-rust, scikit-build, NAPI-RS, multi-module monorepos), each build tool reads its own manifest and stamps that version into its own artifact. The wheel filename comes from
pyproject.toml's [project] version, NOT from Cargo.toml. If you bump only one of them, the artifact name and the tag will disagree, the registry will reject the upload, and the workflow will fail with a confusing "file already exists" error against the previous version's filename. See step 6a for the full list of manifest pairs by project shape, and grep for ^version\s*= across every manifest before tagging.
- Don't use lightweight tags for releases.
git tag vX.Y.Z <sha> (no -a) creates a lightweight tag, just a ref, no tagger metadata, no message. git push --follow-tags deliberately skips these, so the tag won't reach the remote in your release push and you have to remember to push it explicitly with git push origin vX.Y.Z. Use git tag -a vX.Y.Z -m "release vX.Y.Z" <sha> instead, annotated tags carry tagger identity, date, and message (which is what "this is a release" semantically means), get pushed by --follow-tags, and are what gh release and git describe expect.
Cross-references
/flagrare:staleness-audit runs before the commit. This check runs after the commit lands, since release decisions depend on the version manifest + change-entry state post-commit.- Valve's Dota 2 patch notes: https://www.dota2.com/news/updates, the canonical reference for the changelog style this skill enforces.
Why this exists
A project's CHANGELOG is the first thing a prospective user reads after the README. Release tooling makes it easy to generate one and easy to write a bad one, the default flow stitches together author-written summaries verbatim, which often read like a git log. Valve's Dota patch notes are the canonical example of how to write a changelog the audience actually wants: every line is a thing the player can observe, not a thing the engineers did. Same principle: the user wants to know what they can do now, what they need to update, and what bugs they no longer have. Nothing else.
