Release Notes

<!-- AUTO-GENERATED by export-skills.py — DO NOT EDIT -->
---
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.
tags: [release-notes, communication, changelog, product-updates]
---

# 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

```markdown
# 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 |

---

## References

- [Keep a Changelog](https://keepachangelog.com/)
- [Slite: How to Write Release Notes](https://slite.com/learn/release-notes)

<!-- Source: .faos/custom/skills/business/release-notes/SKILL.md -->