| name | release-notes-writer |
| description | Generate ship-ready release notes from specs and tickets. Use this skill when:
- A release is being prepared and you need user-facing release notes
- You need internal (engineering) release notes for a deployment
- You want to generate release notes from completed specs or tickets
|
Release Notes Writer
Generate structured release notes for each release cycle. Produces both user-facing (what changed and why it matters) and internal (technical changes, migration steps) release notes.
Workflow
- Identify release scope — List the features/fixes included
- Read source specs — Read relevant spec files
- Read tickets — If available, read completed tickets for the release
- Categorize changes — Group into: New Features, Enhancements, Bug Fixes, Known Issues
- Write user-facing notes — What changed, why it matters, in plain language
- Write internal notes — Technical changes, migration steps, config changes
- Output — Write to file
User-Facing Release Notes
# [Product Name] — Release Notes {version}
**Release Date:** {DD-MM-YYYY}
**Environment:** {Production / Staging / UAT}
## What's New
### {Feature Name}
{1-2 sentence description of what the feature does and why it matters.}
**Highlights:**
- {Key capability 1}
- {Key capability 2}
## Enhancements
### {Enhancement Name}
{What improved and why it's better now.}
| Before | After |
|--------|-------|
| {Old behavior} | {New behavior} |
## Bug Fixes
| Issue | Fix | Impact |
|-------|-----|--------|
| {description} | {what was fixed} | {who is affected} |
## Known Issues
| Issue | Workaround | Expected Fix |
|-------|-----------|-------------|
| {description} | {workaround} | {target version} |
Internal Release Notes
# Internal Release Notes — {version}
**Release Date:** {DD-MM-YYYY}
**Release Manager:** [your name]
**Deployment Type:** {Rolling / Blue-Green / Canary}
## Changes by Service
| Ticket | Type | Summary | Breaking? |
|--------|------|---------|-----------|
| {KEY-123} | Feature | {Summary} | No |
## Configuration Changes
| Config Key | Old Value | New Value | Service | Notes |
|-----------|-----------|-----------|---------|-------|
## Database Migrations
| Migration | Description | Reversible? | Duration |
|-----------|-------------|-------------|----------|
## Rollback Plan
{Steps to rollback if critical issues found}
## Monitoring Checklist
| Metric | Expected | Alert Threshold | Dashboard |
|--------|----------|-----------------|-----------|
Writing Guidelines
User-Facing
- Lead with benefits, not features — "You can now track X" not "Added X API"
- Use plain language — No technical jargon
- Be specific — "Reports now show time per topic" not "Improved reports"
- Acknowledge bug fixes honestly
Internal
- Be precise — Include ticket numbers, endpoint paths, config keys
- Flag breaking changes prominently
- Include rollback steps
- Reference monitoring dashboards
Anti-Patterns
- Don't write "various improvements" — be specific
- Don't skip the rollback plan for internal notes
- Don't use technical jargon in user-facing notes
- Don't forget known issues — transparency builds trust
Quality Checklist
