Release Notes Writer

---
name: release-notes-writer
description: |
  Trigger when the user asks to write release notes, draft an announcement,
  or produce a user-facing summary of a release. Phrases: "release notes",
  "announce the release", "user-facing changes", "launch post".
allowed-tools:
  - Read
  - Write
  - Bash(git log *)
  - Bash(gh release *)
---

# Release Notes Writer

Produce user-facing release notes from git history and the CHANGELOG. Unlike
the CHANGELOG (reference), release notes are marketing copy.

## Prerequisites

- CHANGELOG.md up to date (use changelog-gen first if not)
- Target audience identified (devs, end-users, enterprise)
- Channel identified (GitHub release, blog post, email, in-app)

## Steps

1. **Read the CHANGELOG entry for this release.** The CHANGELOG is the source
   of truth for what changed. Release notes are the copywriting on top.

2. **Pick the lead.** What is the single most user-facing change in this
   release? That is the headline. Everything else is supporting.

3. **Structure:**
   - Headline (one sentence, active voice, no version number)
   - Opening paragraph: what shipped, why it matters
   - 2-4 bullet highlights with enough detail to be useful (not just names)
   - One "small things" paragraph for minor improvements
   - Upgrade notes if the user needs to take action
   - Thanks section for contributors

4. **Show, do not tell.** For UI changes, include a screenshot or a short
   screen recording. For API changes, include a code example.

5. **Address breaking changes at the top, not buried.** If anything might
   break, flag it in the opening. Never bury breaking changes in bullet 7.

6. **Link to the CHANGELOG** for the full list. Release notes are a summary,
   not a complete catalog.

## Tone rules

- Present tense. "The CLI now supports X" not "We have added X to the CLI".
- Active voice. "Fixed the retry loop" not "The retry loop was fixed".
- Specific. "Improved query speed by 40%" not "Various improvements to
  performance".
- Honest about scope. A small release should be called a small release.

## Output

- Release notes file at `docs/releases/<version>.md`
- GitHub release draft via `gh release create` with the same content
- Optional: blog post draft at `blog/release-<version>.md` if user wants one