---
description: Write user-facing release notes for the changes between two git refs
argument-hint: <from-ref> [to-ref] [audience=users|admins|developers]
allowed-tools:
  - Bash(git log *)
  - Bash(git diff *)
  - Bash(git show *)
  - Bash(git tag *)
  - Bash(git rev-parse *)
  - Read
  - Grep
  - Glob
---

Arguments: `$ARGUMENTS`

Parse: first argument is `FROM`, second (if not an `audience=` value) is `TO` (default `HEAD`). Audience defaults to `users`. If `FROM` is missing, list the 10 most recent tags (`git tag --sort=-creatordate`) and ask.

## Collect

1. `git log --format='%h%x09%s%x09%b' FROM..TO`
2. `git diff --stat FROM..TO`
3. For each change that might be user-facing, read the diff: UI components and copy, public API routes and schemas, CLI flags, config and environment variables, permissions, emails, exports, docs.
4. Read `CHANGELOG.md` entries for this range if present; they are a good source but rewrite them for the audience.

## Decide what is in

Include: new capabilities, changed behavior, removed features, fixes users could have noticed, security fixes (describe impact without exploit details), required actions.
Exclude: refactors, tests, CI, internal tooling, dependency bumps without visible effect.

## Write

```
# <product or repo name> <TO version or date>

## Highlights
- <up to 3 most important changes, one or two sentences each, starting with what the user can now do>

## Improvements
- ...

## Fixes
- <describe the symptom that is now gone, e.g. "Search no longer returns archived projects.">

## Action required
- <upgrade steps, renamed settings, removed options, with exactly what to do>

## Needs confirmation (remove before publishing)
- <changes whose user impact you could not determine from the code>
```

Rules:
- Audience `users`: no code identifiers, file names, ticket IDs, or internal team names.
- Audience `admins`: include config keys, environment variables and migration notes.
- Audience `developers`: include endpoint paths, parameters, SDK method names and deprecation details.
- No performance or quantity claims unless a commit or PR states a measured number; quote it as stated.
- No hype words. Short sentences. Omit empty sections.
- Output Markdown only; do not write any files unless asked.