name: release-notes description: Transform technical changelogs and tickets into user-facing release notes written in benefit language. Use when shipping a release, communicating product updates, or preparing changelog communications.
Release Notes
Transform technical changelogs, PRs, and tickets into clear, user-facing release notes that communicate what changed and why it matters — in language customers understand.
Purpose
Technical changelogs are written for developers. Release notes are written for customers. This skill bridges the gap — translating implementation details into benefit-oriented language that helps users understand, adopt, and appreciate product improvements.
When to Use
- After merging a release branch and preparing for deployment
- Weekly or bi-weekly product update communications
- Monthly product newsletters
- App store update descriptions
- In-app "What's New" notifications
When NOT to Use
- Internal engineering changelogs (keep those technical)
- Security advisories (use a dedicated security disclosure format)
- API breaking change notices (use migration guides)
Required Input
Provide any combination of:
- Git log / PR list for the release
- Completed JIRA/Linear tickets
- Sprint review notes
- PRD sections for shipped features
- Technical changelogs
The Process
Step 1: Categorize Changes
Sort every change into one of these categories:
| Category | Icon | Description |
|---|---|---|
| New Features | New | Entirely new capabilities |
| Improvements | Improved | Enhancements to existing features |
| Bug Fixes | Fixed | Issues that are now resolved |
| Breaking Changes | Breaking | Changes that require user action |
| Deprecations | Deprecated | Features being removed in a future release |
Step 2: Rewrite in Benefit Language
Transform each change from technical to user-facing:
Rules:
- Lead with the benefit, not the implementation
- Use plain language — no jargon, no ticket numbers, no internal terms
- Keep each entry to 1–3 sentences
- Be specific about the improvement (quantify when possible)
Examples:
| Technical (Before) | User-Facing (After) |
|---|---|
| Implemented Redis caching for dashboard queries | Dashboards now load up to 3x faster |
| Fixed null pointer exception in report export | Report exports no longer fail for accounts with empty custom fields |
| Added SAML SSO support (SCIM provisioning) | Enterprise teams can now sign in with their company SSO — no more separate passwords |
| Migrated search to Elasticsearch | Search results are now more accurate and return in under 200ms |
| Refactored payment processing module | (Omit — internal refactoring with no user-visible change) |
| Updated React from v17 to v18 | (Omit — unless there's a user-visible improvement) |
Step 3: Determine Tone
Adjust tone based on audience:
| Audience | Tone | Example |
|---|---|---|
| B2B Professional | Clear, confident, concise | "Dashboards now load up to 3x faster." |
| Consumer / Friendly | Warm, conversational, excited | "Your dashboards just got a speed boost — they load 3x faster now!" |
| Developer / API | Technical, precise, actionable | "Dashboard API response times reduced from ~900ms to ~300ms via query caching." |
Step 4: Structure the Release Notes
Output Format
# Release Notes — [Version or Date]
**Released:** [date]
---
## New Features
### [Feature Name]
[1-3 sentences describing what it does and why it matters to the user]
### [Feature Name]
[description]
---
## Improvements
- **[Area]** — [What improved and the benefit]
- **[Area]** — [What improved and the benefit]
---
## Bug Fixes
- Fixed an issue where [user-visible problem] — [what works now]
- Fixed an issue where [user-visible problem] — [what works now]
---
## Breaking Changes
### [Change Description]
**What changed:** [specific change]
**What you need to do:** [clear migration steps]
**Deadline:** [if applicable]
---
## Deprecations
- **[Feature/API]** will be removed on [date]. [Migration path or alternative].
Filtering Rules
Include:
- Any change that affects what users see, do, or experience
- Performance improvements users would notice
- Bug fixes for reported issues
- Security improvements (without disclosing vulnerability details)
Exclude:
- Internal refactoring with no user-visible impact
- Dependency updates (unless they fix a user-visible issue)
- Build system or CI/CD changes
- Test additions or modifications
- Code style or formatting changes
Distribution Channels
Adapt the release notes for each channel:
| Channel | Format | Length |
|---|---|---|
| In-app notification | 1–3 bullet highlights | Very short |
| Email newsletter | Full release notes with context | Medium |
| Blog post | Narrative with screenshots | Long |
| App store description | Top 3 changes in bullet form | Very short |
| Changelog page | Full structured notes | Medium |
| Slack/Discord | Emoji-formatted highlights | Short |
| API docs | Technical details + migration guides | Technical |
Anti-Patterns
| Avoid | Why | Instead |
|---|---|---|
| Ticket numbers in notes | Customers don't know what PROJ-1234 means | Describe the change in plain language |
| "Various bug fixes" | Dismissive, unhelpful, erodes trust | List specific fixes or say "stability improvements including [example]" |
| Technical jargon | "Optimized SQL query" means nothing to users | "Reports now load faster" |
| Listing internal refactors | Adds noise, no user value | Only include user-visible changes |
| No categorization | Hard to scan, important changes get buried | Use consistent categories |
| Stale release notes | Notes published days/weeks after release | Ship notes with the release |