release-notes

# Release Notes Generator

Generate a release note draft for this repository by analyzing git changes since the previous release. The output is a Markdown code block ready to paste into a GitHub release — do NOT create the release itself.

The version number is provided as an argument (e.g. `/release-notes 0.11.0`). If no version is given, ask for one before proceeding.

## Step 1: Determine the previous release

The "previous release" depends on the version type being drafted:

- **Stable version** (no `-preview`): Find the most recent stable tag, skipping all prereleases. This is because stable release notes cover everything since the last stable release — they aggregate all prerelease changes into one cohesive set of notes.
- **Prerelease** (`-preview.N`): Find the most recent tag of any kind (stable or prerelease). Prerelease notes only cover the incremental delta since the last tag.

Use `git tag --sort=-v:refname` to list tags and pick the right one. Confirm the previous tag to the user before continuing (e.g. "Previous release: v0.10.2 — generating notes for changes since then.").

## Step 2: Gather information

Run these in parallel where possible:

1. **Commit log**: `git log {prev_tag}..HEAD --oneline` — the list of changes
2. **Diff stat**: `git diff --stat {prev_tag}..HEAD` — which files changed
3. **Actual diffs**: Read the diffs of changed source files (`src/`, `styles.css`, `manifest.json`, etc.) to understand what each change actually does at the code level. This is critical — commit messages alone are not enough to write accurate user-facing descriptions.
4. **Issue numbers**: Extract `#NNN` references from commit messages. Note: commit messages often contain PR numbers (from merge commits), not the original issue numbers. Use whatever `#NNN` is in the commit message as-is — the author will verify and correct these during review.
5. **New contributors**: Compare authors before and after the previous tag:
   ```
   git log --format='%aN' {prev_tag} | sort -u        # existing contributors
   git log --format='%aN' {prev_tag}..HEAD | sort -u   # contributors in this range
   ```
   Anyone in the second set but not the first is a new contributor. To find their GitHub username and PR number, use `git log --format='%aN <%aE>' {prev_tag}..HEAD` and cross-reference with `#NNN` in their commit messages. The GitHub username may differ from the git author name — check the commit on GitHub if needed.
6. **Previous prerelease notes** (stable releases only): If drafting a stable release and there were prereleases in the range, read their release notes with `gh release view {tag}`. This helps identify bugs that were introduced and fixed within the prerelease cycle — those should be excluded from the stable release notes since they never affected stable users.

## Step 3: Analyze and categorize

Before writing, think through what each change means from a user's perspective:

- **What can users do now that they couldn't before?** → New features (🌟 New)
- **What existing behavior got better?** → Improvements (🔧 Improvements)
- **What was broken and is now fixed?** → Bug fixes (🐛 Fixes)
- **Did anything get faster?** → Performance (⚡ Performance)
- **Does anything require user action on upgrade?** → Breaking changes (⚠ Breaking Changes)

For stable releases aggregating prereleases: exclude bugs that were both introduced and resolved during the prerelease cycle. Those never affected stable users and do not belong in the stable release notes.

### Detecting breaking changes

Breaking changes are easy to miss in diffs. Actively look for these patterns:

- **Renamed settings keys** in default settings or settings types (e.g., `activeAgentId` → `defaultAgentId`)
- **Renamed command IDs** in plugin.ts `addCommand()` calls
- **Changed or removed public APIs** or exported interfaces
- **Changed default behavior** that users relied on (e.g., a button that now does something different)
- **Removed features or settings**

If any are found, they MUST appear in the `### ⚠ Breaking Changes:` section AND be mentioned in the Upgrade section. If the migration is automatic, say so — users still need to know something changed.

## Step 4: Write the draft

Output the release note as a single Markdown code block. Follow this format exactly.

### Title line

The title is plain text with bold formatting — NOT a Markdown heading. No `#` prefix.

```
{emoji} **{Release Type} (v{version})**
```

Choose the release type and emoji based on content:
- `🔬 **Preview Release**` — all prereleases
- `✨ **Feature Release**` — stable with new features
- `🔧 **Improvement & Bug Fix Release**` — stable with improvements and fixes but no major new features
- `🐛 **Bug Fix Release**` — stable with only bug fixes
- `🔧 **Improvement Release**` — stable with only improvements
- `⚡ **Performance Fix**` — stable with only performance changes
- `🔧 **Maintenance Release**` — stable with only dependency updates or internal changes

### Prerelease warning (prereleases only)

For ALL preview releases — regardless of size — add this immediately after the title line (with a blank line before and after):

```
⚠ **This is a preview release** — Features are experimental and may change. Please report any issues!
```

This is mandatory for every prerelease. Never omit it.

### Summary paragraph

For stable 0.X.0 releases and substantial prereleases with multiple features, add a 1-2 sentence summary after the title (or after the prerelease warning). Patch releases and small prereleases with a single change can skip this.

The summary should focus on the single biggest highlight or theme — not enumerate every change. One sentence is ideal. If you can't pick a single theme, pick the top 2-3 and keep it under two sentences.

### Sections

Include only sections that have content, in this order:

```markdown
### ⚡ Performance:

### 🌟 New:

### 🔧 Improvements:

### 🐛 Fixes:

### ⚠ Breaking Changes:

### 🚀 Upgrade:

--------

### 👋 New Cont