Release notes

Release notes tell the user what changed since the last version. Keep them short. Keep them true. Read the commits and the pull requests, then write what changed.

1. Find the release range

Do not guess. Work out the exact range of commits that will ship.

1. Find the repository owner and name from the remote:

   git --no-pager remote get-url origin

   Parse the owner/repo from it.

2. Find the last published release and its tag with the GitHub tools. Use get_latest_release (or list_releases and take the first entry).

3. Resolve that tag to a commit so you know exactly where the last release ends:

   git --no-pager rev-parse <last-tag>
   git --no-pager log -1 <last-tag>

4. List the commits on main (and main only) that will ship in this release. Use the main branch, not the current working branch:

   git --no-pager log <last-tag>..main --oneline

   The agent tools work too: list_commits with sha: main gives the history. Count the commits. This is the set of changes to write about.

   If there are no commits since the last tag, stop and tell the user there is nothing to release.

2. Read what changed

For each commit in the range, understand what it did. Do not stop at the commit subject.

1. Find the merged pull requests in the range. Commit subjects often carry the PR number, e.g. feat: add tags view (#94). Collect those numbers.
2. For each PR, read its description with pull_request_read using method: get. The PR description often states the intent and the fix in clearer terms than the commit.

3. When a change is not clear from the title and PR body, read the diff. Use pull_request_read with method: get_diff for a PR, or for a bare commit:

   git --no-pager show <commit-sha> --stat
   git --no-pager show <commit-sha>

   Read only what you need to understand the change. Do not quote code back at the reader.

4. Sort each change into one of three buckets:

   • Feature — new functionality the user can see or do.
   • Bug fix — something broken that is now fixed. Note what was broken and what the fix does.
   • Other — dependency upgrades, CI changes, refactors, tooling. These go in the plain Changes list, not in Features or Bug Fixes.

3. Write the release notes

Use the Hemingway approach:

• Short sentences. One idea per sentence.
• Plain words. No jargon when a common word works.
• Active voice. The subject does the thing.
• No filler. "In order to" is just "to". "At this point in time" is "now".
• No marketing. Say what the code does, not how amazing it is.
• No restating the commit subject. The overview adds new information.

Write for a user who runs the app but has not seen this branch of the code.

4. Template

Fill in each section. Drop a section if it has nothing to say. Do not pad.

The Changes list is the only section that lists every PR. Features and Bug Fixes summarize the user-facing changes in plain English.

## Overview

<One to three sentences. What is this release about? Name the big themes. A
user should know what to expect after reading this.>

## ✨ Features

- <Feature in one sentence. What can the user do now that they could not
  before? One bullet per feature. Group small related changes.>

## 🐛 Bug Fixes

- <What was broken, and what the fix does. One bullet per fix.>

## 📝 Changes since <last-tag>

- <PR title or commit subject> (#<PR number>) (<short hash>)
- <PR title or commit subject> (#<PR number>) (<short hash>)

Notes on the Changes list

• Keep the existing line format: - <subject> (#<PR>) (<short hash>).
• Use the short hash, 7 characters.
• If a commit has no PR number, drop the (#NN) part but keep the subject and hash.
• Preserve the original commit subject. Do not rewrite it. This list is the audit trail, not the summary.

5. Before you hand it back

• The range is right. Every commit between the last tag and main is covered, and only those commits.
• Every claim in Overview, Features, and Bug Fixes is grounded in a diff, a commit, or a PR description. No invented detail.
• Features and Bug Fixes describe what the user sees, not the implementation.
• The Changes list includes every PR in the range, in the original format.
• Sentences are short. Words are simple.
• A user can read it in under a minute and know what changed.

6. Next: the in-app highlights

The app shows a short version of Features and Bug Fixes after an update. The release workflow fails if Sources/App/Resources/ReleaseHighlights.json has no entry for the version. After these notes, tell the user to run the release-highlights skill and to merge its change before they publish the release.