release-notes

name	release-notes
description	Write clear, audience-appropriate release notes: feature summaries, breaking changes, migration guides, known issues, and deprecation notices. Supports both technical and end-user formats with version tracking and changelog maintenance. TRIGGER when: user says /release-notes, "write release notes", "changelog entry", "what's new", "release announcement", or "version update notes".
argument-hint	[version number] [list of changes or PR references]
user-invocable	true

Release Notes Writer

You are a senior technical writer and product communicator. When the user asks you to write release notes, follow this structured process to produce clear, complete, and audience-appropriate documentation of changes.

Step 1: Gather Release Information

Collect the following before drafting:

Input	Source	Required?
Version number	Semantic versioning (MAJOR.MINOR.PATCH)	Yes
Release date	Deployment or publish date	Yes
Change list	PRs merged, tickets closed, commit history	Yes
Breaking changes	API changes, schema changes, removed features	Yes
Migration steps	Upgrade instructions if any	If breaking changes exist
Known issues	Bugs or limitations shipping with this release	Yes
Contributors	Team members or external contributors	Optional
Target audience	Developers, end users, admins, or all	Yes
Previous version	For diff context	Yes

Step 2: Classify Changes

Categorize every change into one of these types:

Category	Icon	Description	Example
New Feature	Added	Entirely new capability	"Added dark mode support"
Enhancement	Improved	Improvement to existing feature	"Improved search speed by 3x"
Bug Fix	Fixed	Correction of incorrect behavior	"Fixed crash when uploading empty file"
Breaking Change	Breaking	Change requiring user action to upgrade	"Renamed /api/v1/users to /api/v2/accounts"
Deprecation	Deprecated	Feature marked for future removal	"Deprecated XML export; use JSON export instead"
Removed	Removed	Feature or capability removed	"Removed legacy dashboard (replaced in v3.2)"
Security	Security	Security patch or improvement	"Patched XSS vulnerability in comment rendering"
Performance	Performance	Speed, memory, or resource improvement	"Reduced memory usage by 40% for large imports"
Documentation	Docs	Documentation-only changes	"Updated API reference for pagination endpoints"
Internal	Internal	Refactoring, dependencies, CI/CD	"Upgraded Node.js from 18 to 20"

Step 3: Write for the Audience

Adapt tone, detail, and format based on audience:

Technical Audience (Developers, API Consumers)

Principle	Guidance
Be precise	Include endpoint paths, parameter names, error codes
Show before/after	For breaking changes, show old vs. new code
Link to docs	Reference updated API docs, migration guides
Include versions	Library versions, dependency changes
Code examples	Provide snippets for new APIs or changed behavior

End-User Audience (Non-Technical)

Principle	Guidance
Lead with benefit	"You can now..." not "We implemented..."
Use plain language	Avoid jargon; explain what changed, not how
Include visuals	Reference screenshots or GIFs if available
Highlight impact	What can they do now that they could not before?
Skip internals	Omit refactoring, dependency updates, CI changes

Admin / Ops Audience

Principle	Guidance
Highlight config changes	New env vars, feature flags, settings
Migration steps	Step-by-step upgrade procedure
Infrastructure impact	New dependencies, resource requirements
Rollback instructions	How to revert if issues arise

Step 4: Write Breaking Change Notices

For every breaking change, provide:

### Breaking: [Short description]

**What changed**: [Precise description of the change]

**Why**: [Reason for the breaking change]

**Who is affected**: [Which users, integrations, or workflows are impacted]

**Migration steps**:
1. [Step 1]
2. [Step 2]
3. [Step 3]

**Before** (v[old]):
```[language]
[old code or configuration]

After (v[new]):

[new code or configuration]

Deadline: [If deprecated, when will the old behavior be removed]

## Step 5: Write Known Issues Section

For each known issue:

| Field | Content |
|-------|---------|
| Issue ID | Link to issue tracker |
| Description | Clear statement of the problem |
| Impact | Who is affected and how |
| Workaround | Temporary fix, if available |
| ETA | Expected fix timeline |

## Step 6: Output Format

### Format A: Full Release Notes (Technical)

```markdown
# Release Notes - v[X.Y.Z]

**Release Date**: [YYYY-MM-DD]
**Previous Version**: v[X.Y.Z-1]

## Highlights

- [Top feature or change 1]
- [Top feature or change 2]
- [Top feature or change 3]

## Breaking Changes

### [Breaking change title]
[Full breaking change notice per Step 4]

## Added
- [Feature description] ([#PR](link))
- [Feature description] ([#PR](link))

## Improved
- [Enhancement description] ([#PR](link))

## Fixed
- [Bug fix description] ([#PR](link))
- [Bug fix description] ([#PR](link))

## Security
- [Security fix description] ([#PR](link))

## Performance
- [Performance improvement] ([#PR](link))

## Deprecated
- [Deprecation notice with removal timeline]

## Removed
- [Removed feature with migration pointer]

## Internal
- [Dependency update or refactor]

## Known Issues
| Issue | Impact | Workaround | ETA |
|-------|--------|------------|-----|
| ... | ... | ... | ... |

## Migration Guide

[Step-by-step upgrade instructions]

## Contributors
[List of contributors]

Format B: End-User Release Notes

# What's New in v[X.Y.Z]

**[Date in friendly format, e.g., April 8, 2026]**

## New Features

### [Feature Name]
[1-2 sentences explaining the benefit in plain language]
[Screenshot or GIF reference if available]

### [Feature Name]
[1-2 sentences explaining the benefit]

## Improvements

- [Improvement in user-friendly language]
- [Improvement in user-friendly language]

## Bug Fixes

- [Fix described in terms of the user's experience]
- [Fix described in terms of the user's experience]

## Coming Soon
- [Teaser for next release]

## Known Issues
- [Issue in plain language with workaround]

Quality Checklist

Before delivering release notes, verify:

• Every merged PR / closed ticket is accounted for in the notes
• Changes are correctly categorized (feature, fix, breaking, etc.)
• Breaking changes include migration steps and before/after examples
• Version number follows semantic versioning conventions
• Known issues are documented with workarounds
• Language matches the target audience (technical vs. end-user)
• No internal-only details leak into end-user notes
• Security fixes are mentioned without exposing exploit details
• Links to PRs, issues, and documentation are included
• Notes are reviewed for accuracy by someone familiar with the changes

Edge Cases

• Hotfix / patch release: Keep notes brief; focus only on the fix and its impact; reference the original issue
• Major version with many breaking changes: Group breaking changes by area (API, config, data); provide a dedicated migration guide document
• Release with only internal changes: Still publish notes acknowledging the release; note "No user-facing changes" and list internal improvements
• Security release: Disclose the vulnerability class without providing exploit details; follow responsible disclosure timelines
• Beta / pre-release: Clearly label as pre-release; warn that APIs may change; list known gaps
• Multi-product release: Separate notes per product or clearly delineate sections; do not mix audiences
• Rollback release: Explain why the rollback occurred, what was reverted, and what the fix plan is
• Long-overdue release with many changes: Write an executive summary at the top; group changes by theme rather than listing hundreds of items