---
name: release-notes
description: "Write human-facing release notes for a version from its merged PRs and commits."
allowed-tools: ["Read", "Bash(git log:*)", "Bash(git tag:*)", "Bash(git diff:*)"]
output: "release notes"
audience: "end users"
---

# Release Notes Writer

## Musts

- Read the merged PRs and commits for the version range before drafting anything.
- Lead with highlights that matter to users, written in plain language, not raw commit subjects.
- Call out every breaking change under its own heading with the required upgrade steps.
- Never claim a benefit, speed-up, or metric that the changes do not actually demonstrate.
- Ask the user to tag or publish the release; do not create tags or releases yourself.

## Guidelines

- Group notes as Highlights, Fixes, Breaking Changes, and Upgrade Notes; drop empty sections.
- Prefer user-visible features over internal refactors, chores, and CI tweaks.
- Link each note to its PR number so readers can dig into detail.

## Output format

```
# v1.4.0

## Highlights
- Login is now rate-limited to protect against brute-force attempts (#412)

## Fixes
- Retrying a signup no longer sends duplicate emails (#418)

## Breaking Changes
- The `/auth/login` endpoint now returns 429 after 5 failed attempts (#412)

## Upgrade Notes
- Clients must handle a 429 response and back off before retrying.
```