/release-notes

name: release-notes
description: Rewrite a moraine GitHub release body in the house format — one-sentence pitch, install block, usage-focused "what's new" sections with PR links and optional screenshots, a platform-support table, upgrade notes, and a single deduped auto-generated changelog at the bottom. Use when the user says "/release-notes v0.4.2", "polish the v0.4.2 release notes", or asks to prepare release notes for a tag. NOT auto-invoked by the model.
disable-model-invocation: true

release-notes

You are rewriting a GitHub release body in moraine's house format. The input is a tag (e.g. `v0.4.2`); the output is an updated release body published via `gh release edit <tag> --notes-file <path>`.

Your goal is **usage-focused, not commit-focused**. A reader skimming the release page should understand in 30 seconds: how do I install this, what new thing can I do with it, and am I supposed to do anything when I upgrade?

Usage

`/release-notes v0.4.2` — rewrite the v0.4.2 release body.

If the tag doesn't exist on GitHub yet, stop and explain. Do not create a release; the release is cut by `.github/workflows/release-moraine.yml` on tag push.

Process

1. Gather context

# Current (auto-generated) body. It's usually duplicated 3-6× because the
# release matrix runs softprops/action-gh-release from each target job, each
# time with generate_release_notes: true. You will dedupe in step 3.
gh release view "$TAG" --json body -q .body > /tmp/release-body.current.md

# Previous release tag, for the compare link and upgrade section.
prev_tag="$(gh release list --limit 20 --json tagName,isDraft,isPrerelease -q \
  '[.[] | select(.isDraft==false and .isPrerelease==false and .tagName!=env.TAG) | .tagName] | .[0]')"

# Full list of PRs merged since the previous tag, for context.
gh pr list --state merged --search "merged:>=<prev-tag-date>" --json number,title,url
# or simpler — trust the auto-generated list and just read it.

Also read:

• `scripts/build-python-wheels.py` — keep the "Platform support" table in

sync with `TARGET_TO_WHEEL_PLATFORM`.

• Any PR body that introduces a user-visible feature (via `gh pr view <n>

--json body -q .body`). Prefer the PR's own summary over inventing one.

2. Decide the shape of this release

Before writing, classify the release:

• **Landmark release** — new install path, big UI change, or a breaking

change. Deserves a full-body treatment with install section, screenshots, upgrade notes. v0.4.2 is the canonical example.

• **Patch release** — bug fixes only. Skip "🚀 Install", "🐧 Platform

support", and "⬆️ Upgrading". The "🛠 Under the hood" section becomes the whole body. Still dedupe the auto-generated changelog.

• **Minor release between the two** — include "🆕 What's new" but drop

sections that didn't change. Don't pad.

Don't force a section that has nothing to say.

3. Dedupe the changelog

Every matrix job appended its own `## What's Changed ... **Full Changelog**` block. Keep exactly one. The simplest path: open the current body in an editor, delete all but the first block, move it to the bottom under a `## Changelog` heading.

Check the dedupe with:

grep -c '^## What.s Changed' /tmp/release-body.current.md   # should be 1 after dedupe
grep -c 'Full Changelog'     /tmp/release-body.current.md   # should be 1

4. Write the new sections

Template (copy/paste, then fill in):

# moraine <TAG>

<one-sentence pitch — what is the headline story of this release?>

## 🚀 Install

```bash
uv tool install moraine-cli
moraine up

<one short paragraph expanding on the install command, plus the upgrade recipe for existing users if relevant>

🆕 What's new

<feature title> ([#<PR>](<PR url>))

<2-4 sentences describing the user-visible outcome, in usage-first language. Start with what a user does or sees, not with what you changed.>

<optional: side-by-side screenshot table; see "Screenshots" below>

<repeat per major feature; 2-4 subsections is ideal, 5+ feels padded>

🛠 Under the hood

• [#<PR>](<url>) — one line, user-facing angle if any
• ...

🐧 Platform support

| Platform | Wheel | Notes | |---|---|---| | Linux x86_64 | `manylinux_2_28_x86_64` | glibc 2.28+ (Debian 12+, Ubuntu 20.04+, RHEL 9+, AL2023) | | Linux aarch64 | `manylinux_2_28_aarch64` | same floor | | macOS Apple Silicon | `macosx_11_0_arm64` | macOS 11.0+ | | macOS Intel | — | not published; use `scripts/install.sh` | | Windows | — | not supported yet |

(Pull the tags from `scripts/build-python-wheels.py::TARGET_TO_WHEEL_PLATFORM`. If the platform table hasn't changed since last release, skip this section.)

⬆️ Upgrading from <prev-tag>

moraine down
uv tool upgrade moraine-cli   # or: uv tool install --reinstall moraine-cli
moraine up && moraine status

<only include this section if there's something the user has to do. If it's just a bug-fix release, skip it.>

---

Changelog

<the single deduped auto-generated list from step 3 goes here>

**Full Changelog**: https://github.com/eric-tramel/moraine/compare/<prev-tag>...<TAG>

### 5. Tone + style rules

- **Usage-first sentences.** "You can now see tool-call latencies in the
  monitor" → good. "Adds a new flamegraph component" → bad.
- **Link every PR** the first time you mention a feature: `([#247](url))`.
- **No hedging.** Drop "essentially", "basically", "just". Say what it does.
- **Quote sparingly.** Never copy more than a few lines from a PR body
  verbatim; always rewrite for the release audience.
- **Emojis anchor the major sections only** (🚀 🆕 🛠 🐧 ⬆️). Don't sprinkle
  them through prose.
- **Call out breaking changes in the section they happen in**, with the
  word "removed" or "requires" — not buried in the changelog.
- **Honest platform support.** If Windows isn't supported, the table says
  "not supported yet", not "coming soon".
- **Don't promise canary-week timing.** The runbook in
  `docs/operations/pypi-re