Release Notes Writer

---
name: release-notes-writer
description: Use when generating release notes or a changelog from merged PRs. Triggers on "release notes", "changelog", "what shipped", or pasted `git log` / PR lists.
---

# Release Notes Writer

Release notes are read by humans deciding whether to upgrade or by users discovering what's new. They're not the engineering changelog. Filter ruthlessly, group sensibly, and lead with what users actually care about.

## Required inputs

1. **The PRs / commits** — titles, descriptions, or `git log` output
2. **Audience** — end users / API consumers / library users / internal teams (this changes the voice)
3. **Version number / range** — e.g. v2.4.0, or "since the April 22 ship"
4. **Anything to highlight** — flagship feature, security fix, breaking change

If the user dumps 80 commits and says "make notes," skim them and ask: "These are mostly internal — do you want only user-visible changes, or everything?" Most release notes should keep <30% of merged PRs.

## Filter rules

KEEP if:
- User-visible behavior changed
- API surface changed (endpoint, response shape, function signature)
- Breaking change (always)
- Performance change a user could feel
- Security fix (always, with appropriate disclosure)
- Notable bug fix users complained about

DROP if:
- Internal refactor with no observable change
- CI / build / docs-only commits
- "wip", revert chains that net to no change, dependency bumps unless risky
- Test additions

When in doubt: would a customer reading this care? If no, cut.

## Structure

```
# v2.4.0 — 2026-04-29

## Highlights
2-4 bullets. The headlines. What you'd put in a tweet about this release.

## Breaking changes
[Only if any. List with migration steps.]

- **`api.search()` now returns paginated results.**
  - Before: returned an array
  - After: returns `{ items, nextCursor }`
  - Migrate: pull `.items` from the response, or use `api.searchAll()` for the old behavior.

## New
- 2-4 bullets of new features. User-facing language.

## Improved
- 2-4 bullets of meaningful improvements. Quantify where possible ("3x faster", "supports up to 10x more rows").

## Fixed
- 2-4 bullets of notable bug fixes. Phrase as "Fixed an issue where..." (the user's perspective).

## Security
- [If applicable] CVE references, severity, who's affected, what to do.

## Deprecated
- Things that still work but won't in a future version. Include the timeline.

## Removed
- Things that no longer exist. Should have been deprecated in a prior release.

---

Full changelog: [link]
```

## Voice rules by audience

### End users (consumers, non-technical)
- "You can now sort orders by date" — second person, plain language
- Skip versions, internal names, file paths
- Short. 5-line summary often beats 20 bullets.

### Developers (API / library)
- "The `/v2/search` endpoint now returns paginated results" — third person, specific
- Include code examples for breaking changes
- Reference issue / PR numbers for traceability

### Internal teams
- More detail OK
- Can reference systems and people
- Still group by impact, not by team that did the work

## Anti-patterns

- Restating PR titles unfiltered — "Refactor user model" means nothing to users
- Burying the lede — flagship feature in row 23
- Listing every dependency bump — nobody cares
- Vague "various improvements" — pick the meaningful ones or drop the section
- Calling something a "feature" when it's actually a bug fix users were waiting for
- Soft-pedaling breaking changes — they MUST be loud, with a migration path

## Tone

- Active voice. "Added X" or "X is now supported" beats "X has been added."
- Honest about scope. If the release is mostly bug fixes, say so — users prefer that to inflated lists.
- For breaking changes: direct. "If you rely on `X`, you must update to `Y` before upgrading."

## Output

Markdown. If audience is end users and the input was a long PR list, end with: "Engineering changelog (full list): [link]" — keep the user-facing notes lean.