/release-check

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