---
name: release-notes
description: Drafts user-facing release notes and a CHANGELOG.md entry from the commits since the last git tag. Use when the user asks for release notes, a changelog entry, or what is in the next release.
argument-hint: [version, e.g. 2.4.0]
allowed-tools: Bash(git for-each-ref *) Bash(git branch *) Bash(git log *) Bash(git show *)
---

## Context
- Newest tags: !`git for-each-ref --count=5 --sort=-v:refname --format='%(refname:short)' refs/tags`
- Current branch: !`git branch --show-current`

## Task
1. Range: from the newest tag above to `HEAD`. If there are no tags, ask me which commit to start from. Don't summarize the whole history.
2. Read the commits with `git log <tag>..HEAD --no-merges --format='%h%x09%s%n%b'`. For any commit whose subject is vague ("fix stuff", "wip"), check what it touched with `git show --stat <sha>` before describing it.
3. Version: use `$ARGUMENTS` if I gave one. Otherwise propose the next SemVer number and say why: major if any commit has `!` or a `BREAKING CHANGE:` footer, minor if any `feat`, otherwise patch.
4. Keep only what users notice. Skip `chore`, `ci`, `test`, `build`, `refactor` and docs-only commits unless they change behavior. Mention dependency bumps only when they fix a vulnerability or change supported versions.
5. Write each item as one plain-language sentence about the effect for users, starting with a verb ("Adds CSV export to reports"). Keep issue or PR references that appear in the commit (`#123`). Never guess: if you can't tell what a change does, put it under **Needs a human check**.
6. Produce two blocks:
   - **CHANGELOG.md entry** in Keep a Changelog format: `## [x.y.z] - YYYY-MM-DD` (today's date) with only the sections that have items, in this order: Added, Changed, Deprecated, Removed, Fixed, Security. Breaking changes go first under Changed or Removed, each with a one-line migration step.
   - **Release announcement**: a two-sentence summary plus a short bullet list, under 150 words, for a GitHub release or newsletter.
7. If `CHANGELOG.md` exists, insert the entry under `## [Unreleased]` (or above the newest version heading) without touching older entries, then show me the diff. If it doesn't exist, only print the blocks.

## Never
- Create tags, commit, push, or publish a release. Finish by printing the commands I can run myself, e.g. `git tag -a vX.Y.Z -m "vX.Y.Z"` and `gh release create vX.Y.Z --notes-file <file>`.
- Name commit authors unless the existing changelog already credits people.
- Copy internal ticket links, customer names, hostnames, or anything that looks like a secret from commit bodies.