| name | release-notes |
| description | Write clear, user-focused release notes that explain what changed, why it matters, and how to use it. Outputs release notes for in-app changelogs, emails, blog posts, and developer documentation. |
| argument-hint | ["features shipped","audience (users or developers)","tone (casual or formal)"] |
| allowed-tools | Read, Write |
Release Notes Writer
Release notes are marketing. They tell your users that you are listening to them, that you are investing in the product, and that their experience is getting better. Bad release notes list features; good release notes explain benefits. The best release notes make users excited to open the product and try something new.
Audience and Format Selection
| Audience | Format | Tone | Length |
|---|
| End users (non-technical) | In-app changelog or email | Conversational, benefit-focused | 1-3 sentences per feature |
| Developers / API users | Developer docs / API changelog | Technical, precise | Full code examples where relevant |
| Enterprise accounts | Email or PDF | Professional, business-impact | Summary + details |
| Internal / stakeholders | Slack or internal wiki | Factual, complete | Full details including limitations |
| Public (blog / press) | Blog post | Narrative, feature-highlight | Story-driven, longer |
Feature Framing: From Engineering to User
Engineering language → User language:
| Engineering | User-facing |
|---|
| "Added status field to the integrations endpoint" | "You can now see at a glance which integrations are healthy and which need attention" |
| "Implemented idempotency keys on order creation" | "Creating the same order twice now automatically prevents duplicate charges" |
| "Reduced P99 sync latency from 8s to 1.2s" | "Integrations are now 6x faster — your data syncs in seconds, not minutes" |
| "Fixed null pointer exception in user invite flow" | "Fixed a bug where some team invites failed to send" |
Process
- Gather the changes — what shipped in this release? Include features, improvements, and bug fixes.
- Categorize — new features / improvements / bug fixes / deprecations.
- Write the headline — what is the most important thing in this release?
- Frame each change as a benefit — what can users do now that they couldn't before?
- Include a call to action — how do users try this? Where do they go?
- Add visuals for major features — a screenshot or GIF is worth 300 words.
- Proofread for jargon — read it as a non-technical user.
Output Format
In-App Changelog Entry
[Month] [Year] Update
🎉 What's new
[Feature headline — benefit, not feature name]
[1-2 sentences describing what users can now do. Lead with the user benefit.]
[Optional: Call to action — "Try it now →"]
[Second feature headline]
[1-2 sentences.]
⚡ Improvements
- [Improvement]: [Brief description of what got better and why it matters]
- [Improvement]: [Brief description]
🐛 Bug fixes
- Fixed an issue where [symptom that users experienced]. [Impact: "This affected users who..."]
- Fixed [brief description of fix].
Email Release Announcement
Subject line options (test these):
- Straightforward: "What's new in [Product]: [Top Feature Name]"
- Benefit-led: "See all your integrations at a glance — new in [Product]"
- Curiosity: "[Month] update: the feature you've been waiting for"
Hi [First Name],
[Opening that connects to a pain they know — 1 sentence]
[Feature 1 headline — big and bold]
[2-3 sentences describing the benefit in plain language. What will they do with it? How does it make their day better?]
[Image or GIF showing the feature in action]
[CTA button: "Try [Feature Name] →"]
Also in this update:
- [Feature 2]: [1 sentence benefit]
- [Improvement]: [1 sentence]
- Bug fix: Fixed [issue that was affecting users]
[Closing — optional: tease next update]
[Your name]
[Product team]
P.S. [Optional: direct link to docs, feedback form, or specific call to action]
Developer / API Release Notes
API Version: [X.Y.Z] | Release Date: [YYYY-MM-DD]
Breaking Changes
Review these before updating to this version.
[Change name]
- What changed: [Technical description]
- Why: [Business or technical reason]
- Migration: [Specific steps to update]
- Deadline: [If applicable — when old behavior is removed]
- Example:
# Before
GET /api/v1/integrations
→ { "id": "...", "user_id": "..." }
# After
GET /api/v2/integrations
→ { "id": "...", "user": { "id": "...", "email": "..." } }
New Features
[Feature Name]
Endpoint: POST /api/v2/integrations/{id}/retry
[Description of what it does and when to use it]
curl -X POST https://api.example.com/v2/integrations/int_abc123/retry -H "Authorization: Bearer $TOKEN"
Response:
{
"integration_id": "int_abc123",
"status": "retry_queued",
"estimated_completion": "2024-03-15T10:35:00Z"
}
Notes:
- Rate limited to 5 retries per integration per hour
- Returns 409 if integration is currently syncing
- Returns 422 if integration has been disabled
Deprecated
The following features will be removed in v3.0 (target: June 2024):
| Deprecated | Replacement | Reason |
|---|
user_id field on order response | user.id in nested user object | Consistency with other endpoints |
GET /api/v1/status | GET /api/v2/integrations/{id}/health | More granular and real-time |
Worked Examples
Bad: "Added integration retry functionality to the integration management interface."
Good: "You can now retry a failed sync with one click — no more waiting for the next scheduled sync or contacting support for transient failures."
Bad: "Fixed NPE in webhook delivery service."
Good: "Fixed a bug where webhooks occasionally failed to deliver for events with empty payloads. If you noticed missing webhook events, this is now resolved."
Bad: "Performance improvements."
Good: "Sync times for large integrations (10,000+ records) are now 6x faster. A sync that previously took 3 hours now completes in ~30 minutes."
Changelog Frequency and Categories
| Category | When to Include | User Sees |
|---|
| New features | Always | "What's new" / "🎉" |
| Performance improvements | If user-perceptible | "Improvements" |
| Bug fixes (user-visible) | Yes | "Bug fixes" |
| Bug fixes (internal) | Usually no | Skip unless caused user pain |
| Security patches | Brief mention | "Security updates" — no details |
| Infrastructure changes | No | Skip |
| Deprecations | Yes, with timeline | "Deprecation notice" |
Rules
- Lead with the benefit, not the feature — "you can now..." not "we added...".
- One sentence per feature for end users — if you need three sentences, the feature needs better UX.
- Visuals for anything visual — a screenshot communicates UI changes better than any description.
- No jargon for end-user notes — if you wouldn't say it in conversation, don't write it.
- Acknowledge what you fixed — don't bury bug fixes; users who were affected feel heard when you name it.
- Be specific about performance — "6x faster" not "improved performance".
- Include a call to action — tell users where to go to try the thing.
- Separate developer and user notes — API changes don't belong in the end-user changelog.
- Deprecation notices require timelines — "being deprecated" without a date is useless; "removed June 2024" is actionable.
- Write it before shipping — release notes written after the fact lack the context of someone who designed the feature.
