/writing-release-notes

name: writing-release-notes
description: Write user-facing release notes for a Bitwarden release from a Jira release tag and the #release Slack thread. Use when asked to "write release notes", "draft release notes", "generate release notes", "write app store notes", or any request to produce external-facing release copy for a given version.
allowed-tools: mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__search_issues, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue_comments

Writing Release Notes

Produce concise, user-facing release notes for a Bitwarden release. The output is what customers read — on GitHub, in the App Store, or in Google Play — so every word should be benefit-oriented, jargon-free, and accurate about what users will actually experience.

Prerequisites

Automated Jira lookups require the `bitwarden-atlassian-tools` plugin (its MCP server exposes `search_issues`, `get_issue`, and `get_issue_comments`). Without it, or when running in a Claude.ai Project (MCP tools are unavailable there), fall back to asking the user to paste the release page content and the Slack thread text directly — the rest of this skill works identically either way. There is no Slack MCP integration in this marketplace; the Slack thread is always gathered by asking the user to paste it.

Step 1: Gather Inputs

Gather two inputs before writing anything:

1a. Jira Release Page

Ask the user for the Jira release page URL (e.g. `https://bitwarden.atlassian.net/projects/CL/versions/12345/tab/release-report-all-issues`) or the release version name (e.g. `2025.7.0`).

If `search_issues` is available, resolve the query:

• From a URL, extract the numeric version ID (the segment after `/versions/`) and query by ID: `fixVersion = 12345 ORDER BY issuetype ASC`
• From a version name, quote it: `fixVersion = "2025.7.0" ORDER BY issuetype ASC`

Call `search_issues` with `fields: ["summary", "issuetype", "labels", "components", "status", "description"]`, and page through results using the returned `nextPageToken` until none is returned. For each issue, capture summary, issue type, labels, components, status, and any feature flag references found in the description. Feature flag references usually surface more completely in the Slack thread (Step 1b); only call `get_issue_comments` for individual issues where the flag is ambiguous after checking both sources.

If MCP tools are not available (web app context), ask the user to paste the release page content or a list of ticket summaries directly into the conversation.

1b. #release Slack Thread

The #release Slack thread is posted weekly and specifies which feature flags are toggled for the release. This is critical for two reasons:

• **Include**: Only user-facing changes whose feature flag is being enabled in this release (or that have no flag) should appear in the notes.
• **Flags enabled with no matching issue in this release**: don't assume there's nothing to report — see the Step 3 investigation.
• **Server releases — flag removals**: When a feature flag is being fully removed from the server codebase, this signals that self-hosted users are gaining access to the feature. These must appear in the release notes.

Ask the user to paste the thread content.

Parse the thread to extract:

• Release version and date
• List of flags being **enabled** for this release (per platform if specified)
• List of flags being **removed** (for server releases — capture both the flag identifier and any associated feature description from the ticket or thread)
• Any PM or engineering notes about what to highlight or suppress

Step 2: Determine Release Scope

Identify:

• **Which repo/product** is being released (clients, server, mobile, browser extension, CLI, desktop)
• **Which platforms** are covered (web app, desktop, browser extension, mobile iOS, mobile Android, CLI)
• **Release version** number

If the release covers multiple repos with separate release notes (e.g., clients and server each have their own GitHub release), confirm with the user whether they want notes for all or one.

Step 3: Filter to User-Facing Changes

Go through every issue in the release and classify it. Only items that pass the filter appear as named bullet points.

Include as a named bullet point

• New user-visible features or capabilities
• UI or UX changes users will notice
• Policy and admin setting changes (including new enforcement options)
• Performance improvements users will perceive
• Significant accessibility improvements
• New onboarding flows, product tours, or setup wizards
• Checkout, billing, or subscription flow changes
• Items whose feature flag is confirmed **enabled** in this release's Slack thread
• Flags confirmed **enabled** in the Slack thread with no matching issue in this release's Jira list, but only once the investigation below shows the guarded feature is itself user-facing

Collapse into the catch-all line

• Internal refactors, code cleanup, or architecture changes with no user-visible effect
• Dependency upgrades with no user-visible change
• Test coverage additions
• Logging, telemetry, or analytics instrumentation
• Items behind a feature flag that is **not** being enabled in this release
• Flags confirmed **enabled** in this release whose guarded work turns out to be an internal refactor, infrastructure change, or other item that would collapse under these same rules if it had shipped with a ticket in this release
• Minor copy or label tweaks not worth their own bullet
• Bug fixes that are too narrow or edge-case to be meaningful to most users

Always include (never collapse) — server releases only

Feature flags that are **fully removed** from the server codebase in this release. Flag removal is the moment self-hosted users gain access to a feature. Write each removal as a user-facing line describing what the feature does — no