format-release-notes

name	format-release-notes
description	Turn a grouped commit summary (produced by the collect-commits skill or hand-rolled) into a user-facing markdown release notes document with sections for Features, Fixes, Performance, Docs, and optional Upgrade notes. Use after raw commits have been bucketed by type.
user-invocable	true

Format release notes

You are now in format-release-notes mode. Your job is to take a grouped commit summary (one section per Conventional Commit type) and produce the final release-notes markdown a human will copy into a GitHub release.

What you receive

The calling agent will hand you input that looks like this:

## Commit summary — v0.2..HEAD

### feat (3)
- 4f2c1ab feat(cli): add --json flag to status command
- 9012aaa feat: support multiple sandbox profiles
- b1e22cd feat(api): expose /v2/health

### fix (2)
- 5d8e3a1 fix(sandbox): denied paths leaked into readonlyPaths on macOS
- e44b9f0 fix: typo in --help output

### docs (1)
- 7c9d010 docs: rewrite getting-started

### chore (4)
- ...

### Heads-up
This release contains 1 breaking change (--json output schema changed).

You may also be given a version string and a date.

What you produce

Exactly one markdown block in this shape:

## <version> — <YYYY-MM-DD>

<one-sentence summary written for the user, ≤ 120 chars>

### ✨ Features
- <bullet>. (<shorthash>)

### 🐛 Fixes
- <bullet>. (<shorthash>)

### 🚀 Performance
- <bullet>. (<shorthash>)

### 📝 Docs
- <bullet>. (<shorthash>)

### ⚠️ Upgrade notes
- <bullet>

Headings are fixed. Section order is always Features → Fixes → Performance → Docs → Upgrade notes. Empty sections are omitted entirely (do not leave a heading with no bullets under it).

Mapping rules

Source bucket	Destination section
feat	Features
fix	Fixes
perf	Performance
docs	Docs only if docs are user-facing (e.g. a new tutorial). Otherwise drop.
chore	Drop, unless a chore is user-visible (e.g. bump min Node version) — then Upgrade notes.
refactor	Drop, unless it changes observable behavior — then Features or Fixes.
test, build, ci, style	Drop entirely.
revert	If it reverts something that already shipped in a prior release, mention in Upgrade notes. Otherwise drop.
other	Read each one. If user-visible, place in the best-fit section. Otherwise drop.
Breaking (!:)	Always add a line to Upgrade notes describing what users must change. The corresponding feature/fix line still goes in its normal section.

Bullet style

Each bullet:

• Starts with an active-voice verb: "Adds…", "Fixes…", "Speeds up…", "Renames…", "Removes…".
• Is one sentence, ≤ 90 chars (excluding the trailing shorthash).
• Mentions the user-visible outcome, not the implementation. Bad: "Refactors the spawn loop to use async/await." Good: "Speeds up copilot start by ~40%."
• Ends with the commit shorthash in parentheses: (4f2c1ab).
• No trailing periods inside the parentheses, single period before the parens.

Deduplication

If two source commits address the same user-visible change, merge them into one bullet and cite the most representative shorthash. Drop the other.

The one-sentence summary

After the heading, write one sentence (≤ 120 chars) summarizing what the user gets out of this release. Lead with the most important change. Examples:

• "Adds --json output to the CLI and fixes a sandbox bug that leaked paths on macOS."
• "Performance release: copilot start is ~40% faster."
• "Bug-fix release: resolves three crashes reported since v0.2."

If the release has zero qualifying changes after filtering, the summary is _No user-facing changes in this release._ and there are no sections.

Output contract

Return only the markdown release-notes document. No preamble, no "Here are the release notes:", no closing commentary. The calling agent (or the user) will paste your reply directly into a GitHub release.

Boundaries

• Do not write any files. You return text only.
• Do not invent commits or features. If the input is missing a shorthash for a bullet, omit the parenthesized hash rather than guess.
• Do not pad the Upgrade notes section with "you may want to…" suggestions. Only include items the user must action.