Write release notes

Turn a changelog into notes a user can act on. The trick is telling the model what to leave out.

When to use it

Turning a changelog into something a user reads in under a minute and acts on.

What it prevents

Notes that list everything and communicate nothing. The instruction to omit refactors and internal tickets is doing the work — completeness is the enemy of a good release note.

The prompt

Write release notes for version 2.4 from the changelog below.

### Audience
Existing users who want to know whether this release affects them, in under a minute.

### Context
Version 2.3 broke a workflow and users are wary of upgrading. Trust matters more than completeness here.

### Requirements
- Length: Under 200 words.
- Output format: Markdown, grouped under Added, Fixed, and Breaking.
- Say plainly what a user must do if a change breaks them.
- Avoid: internal ticket numbers, refactor commits, and anything with no user-visible effect.

### Example of the wanted output
## Breaking
The `--legacy` flag is gone. Replace it with `--compat` before upgrading.

### Changelog
"""
- fix: null check in parser
- feat: --compat flag
- chore: bump deps
"""

Why each part is there

Every section of that prompt exists because a specific failure happens without it. These are the checks it passes, and what each one is protecting you from:

• States a concrete task — why this matters
• Avoids vague language — why this matters
• Specifies an output format — why this matters
• Gives context or audience — why this matters
• Avoids dangling references — why this matters
• Includes an example — why this matters
• Separates data from instructions — why this matters
• Avoids over-aggressive phrasing — why this matters
• Defines what a good answer looks like — why this matters

How to adapt this one

Point it at your own changelog and keep the grouping — Added, Fixed, Breaking — because Breaking is the section users actually scan for. The instruction that does the work is the exclusion list: internal tickets, refactors, dependency bumps. Adapt that list to whatever noise your changelog collects, and the notes stay about the user rather than the repo.

The mistake this prompt avoids

Shipping the changelog with nicer formatting. A changelog is written for the team; release notes are written for the user, and most of a changelog has no user-visible effect. If a line would not change what a reader does next, it does not belong in the notes. Completeness is the failure mode here, not the goal.

A variation

For a major version with a migration, promote Breaking to the top and give each breaking change its own before/after line — the exact flag or call that changed. Users skim release notes to answer one question: “will this break me, and what do I type to fix it.” Answer that first and the rest can be terse.

Check your version

Once you have adapted it, run it through the checker. The same nine checks that graded this page will grade yours, free and in your browser — paste it in, or build one from scratch by answering a few questions.