release-notes

name	release-notes
description	Writes user-friendly release notes with categorized changes, migration guides, and known issues. Use when communicating software updates to users and stakeholders.
allowed-tools	Read Write Glob
metadata	{"author":"matthewhitcham","version":"1.0"}

Release Notes

When to Use This Skill

Use this skill when you need to:

• Write release notes for a software update or new version
• Communicate breaking changes with migration guides
• Document known issues and workarounds for a release
• Create release notes that serve both technical and non-technical audiences

DO NOT use this skill for product changelogs (ongoing, shorter entries), feature announcements (marketing-focused), or internal engineering post-mortems. This is for formal release notes tied to a specific version or update.

---

Core Principle

RELEASE NOTES SERVE TWO AUDIENCES SIMULTANEOUSLY — USERS WHO WANT TO KNOW WHAT CHANGED AND DEVELOPERS WHO NEED TO KNOW WHAT BROKE. WRITE FOR BOTH.

---

Phase 1: Brief

Required Inputs

Input	What to Ask	Default
Version number	"What is the version or release identifier?"	No default — must be provided
Release date	"When is this release going live?"	Today
Changes list	"List all changes — features, improvements, fixes, breaking changes."	No default — must be provided
Breaking changes	"Are there any breaking changes that require user action?"	None
Known issues	"Are there any known issues shipping with this release?"	None
Audience	"Are readers technical developers, end users, or both?"	Both

GATE: Confirm the brief before writing.

---

Phase 2: Categorize Changes

Sort every change into one of these categories:

• Highlights — Major features or changes worth calling out at the top
• New Features — Capabilities that did not exist before
• Improvements — Enhancements to existing functionality
• Bug Fixes — Issues resolved in this release
• Breaking Changes — Changes that require user action or code updates
• Deprecations — Features being phased out (with timeline)
• Known Issues — Problems shipping with this release (with workarounds)

Present the categorized list for confirmation.

GATE: Confirm categorization before writing the full notes.

---

Phase 3: Write

Release Notes Format

# Release Notes — v[X.Y.Z]
**Release Date:** [Date]

## Highlights

[1-2 paragraph summary of the most important changes in this release. Write for someone skimming — they should understand the impact in 30 seconds.]

## New Features

- **[Feature name]** — [What it does and how to access it. 1-2 sentences.]

## Improvements

- **[Area improved]** — [What changed and the user benefit. 1 sentence.]

## Bug Fixes

- **[Issue description]** — [What was broken and confirmation it is resolved. 1 sentence.]

## Breaking Changes

### [Change title]
**Impact:** [Who is affected and how]
**Action required:** [Exactly what users must do]
**Migration guide:** [Step-by-step instructions]
**Deadline:** [When the old behavior stops working]

## Deprecations

- **[Feature name]** — Deprecated as of this release. Will be removed in v[X.Y.Z]. Use [alternative] instead.

## Known Issues

- **[Issue description]** — [Workaround if available. Expected fix in v[X.Y.Z].]

Writing Rules

• Highlights section is mandatory — even for small releases, summarize the key changes in 2-3 sentences
• User-facing language — translate technical changes to user impact
• Specific bug fix descriptions — "Fixed login failure on Safari 17" not "Fixed authentication bug"
• Breaking changes get full treatment — impact statement, action required, migration steps, and deadline
• Known issues include workarounds — never list a known issue without a workaround or expected fix date

---

Phase 4: Polish

1. Migration Guide (if breaking changes exist)

Write a step-by-step migration guide:

• Before/after code examples
• Configuration changes required
• Timeline for backward compatibility
• Support contact for migration issues

2. Distribution Plan

Channel	Format	Audience
In-app notification	Highlight summary + link	All users
Email	Full release notes	Opted-in users
Documentation site	Complete notes with migration guides	Developers
Blog	Highlights only with feature focus	Prospects and public
Social media	One-liner about the biggest change	General audience

3. Quality Checklist

## Release Notes Checklist

- [ ] Version number and date are clearly stated
- [ ] Highlights section summarizes key changes in 2-3 sentences
- [ ] All changes are categorized (New, Improved, Fixed, Breaking, Deprecated)
- [ ] Breaking changes include impact, action required, and migration steps
- [ ] Bug fixes describe what was broken specifically
- [ ] Known issues include workarounds or fix timelines
- [ ] Language is understandable by non-technical users
- [ ] No internal jargon, ticket numbers, or code references in user-facing notes
- [ ] Distribution plan covers all relevant channels
- [ ] Deprecation timeline is specific (version number and date)

---

Example

Version: v2.4.0 Release date: February 27, 2026

Highlights excerpt: "Version 2.4.0 introduces recurring invoices and a redesigned dashboard. Recurring invoices let you schedule automatic billing on any cadence — set it once, and invoices send themselves. The new dashboard loads 60% faster and surfaces your most important metrics at a glance."

Breaking change excerpt:

### API v1 Endpoints Deprecated

**Impact:** All users making API calls to api.example.com/v1/ endpoints.
**Action required:** Update your API calls to use /v2/ endpoints by April 30, 2026.
**Migration guide:**
1. Replace /v1/ with /v2/ in all endpoint URLs
2. Update the Authorization header format (see docs)
3. Test with the sandbox environment
4. Switch production calls before April 30

**Deadline:** April 30, 2026. After this date, /v1/ endpoints will return 410 Gone.

---

Anti-Patterns

• Dumping git commit messages — "Fixed #4521" and "Refactored user service" are not release notes. Translate to user impact.
• Hiding breaking changes — burying them at the bottom guarantees angry users. Lead with breaking changes or highlight them prominently.
• No migration guide — telling users something broke without telling them how to fix it is worse than not telling them at all.
• Skipping known issues — users will find them anyway. Documenting them proactively builds trust.
• Marketing fluff — release notes are not blog posts. Be factual, specific, and concise.

---

Recovery

• Tiny release with few changes: Write a brief note. Even "Bug fixes and performance improvements" is better than silence, but add specifics.
• Major breaking change with complex migration: Create a dedicated migration guide document. Link from the release notes.
• Known issue with no workaround: State the issue, acknowledge the impact, and provide a timeline for the fix. Offer direct support contact.
• Release was rolled back: Publish a note explaining the rollback, what was affected, and when the re-release is expected.