Release Notes

Release Notes

Translate engineering output into customer-facing value. The reader's only question is "what can I do now that I couldn't before, and does anything I rely on change?"

Before writing

1. Get the raw material: commits, merged PRs, tickets, or a verbal list. If given repo access, extract changes since the last tag/release programmatically.
2. Ask the audience and venue: in-app changelog, email, docs page, or app-store listing. App-store copy has length limits and no markdown; email needs a subject line.
3. Ask which changes are breaking, behavior-altering, or require user action. These lead the notes regardless of how exciting anything else is.

Workflow

1. Filter ruthlessly. Internal refactors, dependency bumps, and invisible fixes don't belong in customer notes. If a release is all internals, the honest note is short — don't inflate.
2. Translate feature → outcome. Not "Added CSV export endpoint" but "Export your reports as CSV — pull your data into Excel or your BI tool." Every entry passes the "so what" test: the sentence must contain what the user can now do.
3. Order by reader impact: ⚠ breaking/action-required → new capabilities → improvements → fixes. Never bury a breaking change under features.
4. Fixes get dignity. "Fixed an issue where exports over 10k rows failed" — specific enough that the affected user recognizes their bug. "Various bug fixes and improvements" is a non-statement; use it never.
5. Match the product's voice (ask for a sample or check existing notes): playful, neutral, or enterprise-formal. Jokes age badly in enterprise changelogs.
6. Link out where the feature needs explanation — one line + "Learn more" beats a paragraph.

Output format

# [Product] [version] — [date]
[One-sentence release theme, if the release has one. Skip if it doesn't.]

## ⚠ Action required / Breaking
- [Change · who's affected · what to do · deadline]

## New
- **[Capability name]** — [what you can now do, one sentence]. [Learn more](link)

## Improved
- [Outcome-framed improvement, with numbers where real: "Search results now load 2× faster"]

## Fixed
- [Specific, recognizable fix]

Quality bar — self-check

• Every entry names a user-visible outcome. Entries that only make sense to the eng team get rewritten or cut.
• Breaking changes are first and impossible to miss.
• Numbers are real — "2× faster" only if measured; otherwise "faster".
• No "various fixes and improvements".
• Length fits the venue (app-store limits, email scannability).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ramanbamba
• Source: ramanbamba/10x-pm
• License: MIT

Install and usage instructions live in the source repository linked above.