frank-luongt/plugins/faos-pm/skills/release-notes

<!-- AUTO-GENERATED by export-plugins.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

# 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
• Slite: How to Write Release Notes

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