---
name: writing-release-notes
description: Writes user-facing release notes and changelog entries in the house style — benefit-first, plain language, grouped by Added/Improved/Fixed. Use when the user asks to write, draft, or edit release notes, a changelog entry, a "what's new" section, or a version announcement for end users. Do not use for git commit messages, internal PR descriptions, or API reference documentation.
---

<!--
Author: Simon-Pierre Boucher
Contact: contact@spboucher.ai
-->

# Writing Release Notes

## When to use / when NOT to use
- **Use for:** release notes, changelog entries, "what's new" copy, version announcements — anything a **customer or end user** will read about a release.
- **Do NOT use for:** git commit messages, PR titles/descriptions, internal engineering changelogs, API reference docs, or marketing landing pages. Those have different audiences and conventions — write them normally.
- If the audience is ambiguous, ask one question: "Is this for end users or for engineers?" Apply this skill only for end users.

## House style — the five rules

1. **Lead with the user benefit, not the implementation.**
   - ✅ "Search results now load twice as fast."
   - ❌ "Migrated the search index to OpenSearch 2.x with query caching."

2. **Plain language, present tense, second person where natural.**
   - ✅ "You can now export reports as PDF."
   - ❌ "PDF export functionality has been implemented."
   - Never use: "leverage", "utilize", "robust", "seamless", "enhanced UX", ticket IDs, or internal codenames.

3. **Group entries under exactly three headings, in this order: `### Added`, `### Improved`, `### Fixed`.** Omit a heading only if it has no entries. One bullet per change, max 2 sentences per bullet.

4. **Every breaking change gets a `> **Breaking:**` blockquote at the TOP of the notes,** before any heading, stating what breaks and the one-line migration action. Never bury a breaking change in a bullet.

5. **Cut the noise.** Never include: dependency bumps with no user impact, internal refactors, test/CI changes, or "various bug fixes and improvements" filler. If a change has no observable effect for the user, it does not appear.

## Workflow

1. Collect the changes (diff, commit list, or user's description). Discard anything rule 5 excludes.
2. Classify each remaining change as Added / Improved / Fixed; identify breaking changes.
3. Rewrite each change benefit-first (rule 1) in plain language (rule 2).
4. Assemble in the output format below.
5. Self-review against the five rules; fix violations before delivering.

## Output format

```markdown
## <Product name> <version> — <YYYY-MM-DD>

> **Breaking:** <what breaks + migration action>   ← only if applicable

<One-sentence summary of the release theme.>

### Added
- <bullet>

### Improved
- <bullet>

### Fixed
- <bullet>
```

Deliver in chat by default; write to `CHANGELOG.md` (prepended above previous entries) only if the user names a file or the repo already has one.

## Edge cases
- **No user-visible changes at all** → say so and propose the one-liner: "This release contains internal improvements only." Do not invent benefits.
- **Unclear whether a change is user-visible** → include it under Improved, phrased by observable effect; flag your assumption to the user.
- **Version or date unknown** → use placeholders `<version>` / `<date>` and tell the user to fill them in.

## More examples
Full positive/negative example pairs, including a complete before/after release: see [references/examples.md](references/examples.md).