release-cut
Turn accumulated merged work into a clean tagged release: changelog roll-up, version bump, tag, GitHub release, and a drafted announcement. Drafts are drafts; nothing gets posted to social platforms by this skill.
Preconditions
Check before touching anything; stop and report if any fail:
- On the default branch, clean tree, up to date with the remote
- CI green on the head commit
- Tests pass locally (run them, do not assume)
Steps
- Scope the release.
git log <last-tag>..HEAD --oneline plus the CHANGELOG's Unreleased section. If the two disagree, reconcile first; the log is the truth, the changelog is the narrative.
- Pick the version. Semver from the actual changes: breaking = major (or minor pre-1.0), features = minor, fixes State the reasoning in one line.
- Roll the changelog. Move Unreleased under the new version with today's date. Entries describe user-visible effects, not commit subjects. Start a fresh empty Unreleased section.
- Bump the version everywhere the project declares it (package manifest, version constant, docs). Grep for the old version string to catch stragglers.
- Commit and tag.
chore: release vX.Y.Z then an annotated tag: git tag -a vX.Y.Z -m "vX.Y.Z".
- Push, then release. Push branch and tag, then
gh release create vX.Y.Z --title "vX.Y.Z" --notes-file <(extracted changelog section).
- Draft the announcement. Two or three sentences per platform the user actually publishes to: what shipped, why anyone should care, link. Hand the drafts to the user; do not post.
Rules
- Never invent changelog entries. Every line traces to a commit or PR.
- Never release with failing or skipped tests "because the failure is unrelated". Fix or explicitly get the user's call.
- Version appears in code AND tag AND changelog AND release title. All four match or the release is wrong.
- If nothing user-visible changed since the last tag, say so and recommend not releasing.
Common mistakes
- Tagging before pushing the release commit, leaving the tag pointing at an unpushed SHA.
- Release notes that are commit logs. Readers want effects, not plumbing.
- Bumping versions per merged feature. Accumulate, then release when there is a story to tell.
1---2name: release-cut3description: Use when the user asks to cut a release, tag a version, publish a release, or roll up the changelog. Not for routine merges; releases happen on request, not per feature.4license: MIT5---67# release-cut89Turn accumulated merged work into a clean tagged release: changelog roll-up, version bump, tag, GitHub release, and a drafted announcement. Drafts are drafts; nothing gets posted to social platforms by this skill.1011## Preconditions1213Check before touching anything; stop and report if any fail:14- On the default branch, clean tree, up to date with the remote15- CI green on the head commit16- Tests pass locally (run them, do not assume)1718## Steps19201. **Scope the release.** `git log <last-tag>..HEAD --oneline` plus the CHANGELOG's Unreleased section. If the two disagree, reconcile first; the log is the truth, the changelog is the narrative.212. **Pick the version.** Semver from the actual changes: breaking = major (or minor pre-1.0), features = minor, fixes only = patch. State the reasoning in one line.223. **Roll the changelog.** Move Unreleased under the new version with today's date. Entries describe user-visible effects, not commit subjects. Start a fresh empty Unreleased section.234. **Bump the version** everywhere the project declares it (package manifest, version constant, docs). Grep for the old version string to catch stragglers.245. **Commit and tag.** `chore: release vX.Y.Z` then an annotated tag: `git tag -a vX.Y.Z -m "vX.Y.Z"`.256. **Push, then release.** Push branch and tag, then `gh release create vX.Y.Z --title "vX.Y.Z" --notes-file <(extracted changelog section)`.267. **Draft the announcement.** Two or three sentences per platform the user actually publishes to: what shipped, why anyone should care, link. Hand the drafts to the user; do not post.2728## Rules2930- Never invent changelog entries. Every line traces to a commit or PR.31- Never release with failing or skipped tests "because the failure is unrelated". Fix or explicitly get the user's call.32- Version appears in code AND tag AND changelog AND release title. All four match or the release is wrong.33- If nothing user-visible changed since the last tag, say so and recommend not releasing.3435## Common mistakes3637- Tagging before pushing the release commit, leaving the tag pointing at an unpushed SHA.38- Release notes that are commit logs. Readers want effects, not plumbing.39- Bumping versions per merged feature. Accumulate, then release when there is a story to tell.
escoffier-labs