Release Notes

Release Notes (Agent Sessions)

CHANGELOG vs. release notes (read first)

These are two different documents with opposite jobs. Do not apply this skill to the first one.

The CHANGELOG is both the source history and the origin of the derived notes — because the deploy tool generates Sparkle/GitHub notes from it (see "How the derived notes are generated"). While developing, [Unreleased] may hold flat granular bullets; that's fine. At release, you curate that section into structured headings by applying the rule below. Don't delete real history — demote it to ### Improvements. Everything below is the curation rule.

Overview

Release notes describe the net change from the last shipped release to this one — the delta a user actually experiences when they update. They are not a replay of the CHANGELOG, and not a log of the work done during the cycle.

Core principle: ship the destination, not the journey. A user who updates from X to Y never saw any intermediate state. Everything that was built, refined, redesigned, and fixed between X and Y and never shipped to them is invisible — and must stay invisible in the notes.

This is the single rule most release notes get wrong, because the author lists what they worked on (commits, effort) instead of what changed for the user (the diff between two shipped versions).

The Iron Rule

A change earns a line only if it is observable as a difference between the previous shipped release and this one.

Two direct consequences:

1. A feature that did not exist in the previous release collapses to one description. Every refinement, "redesign," layout pass, polish commit, and bug fix made to that feature during this cycle folds into the feature's description. The user never had the rough version, so there is nothing to "fix" or "redesign" from their point of view. List the feature once, as it ships.

2. A bug fix earns a line only if the broken behavior shipped in the previous release. If the bug was introduced and fixed within this cycle, the user never received it — drop it. Pre-release stabilization, validation fixes, and "fixed the thing we just built" are not user-facing bug fixes.

Violating the letter of this rule violates the spirit of it. "But we worked really hard on the runway toolbar" is effort, not a user-visible delta. Effort does not earn a line.

Decision: does this change earn a line?

digraph earns_line {
    "Change from git log / dev notes" [shape=box];
    "Did the affected feature exist in the previous shipped release?" [shape=diamond];
    "Is it a bug FIX?" [shape=diamond];
    "Did the BROKEN behavior ship in the previous release?" [shape=diamond];
    "Fold into the feature's single description" [shape=box];
    "List as a Bug Fix" [shape=box];
    "Drop it (user never saw it)" [shape=box];
    "List as a New Feature" [shape=box];

    "Change from git log / dev notes" -> "Did the affected feature exist in the previous shipped release?";
    "Did the affected feature exist in the previous shipped release?" -> "Is it a bug FIX?" [label="yes"];
    "Did the affected feature exist in the previous shipped release?" -> "New?" [label="no"];
    "New?" [shape=diamond, label="Is this the feature's first ship?"];
    "New?" -> "List as a New Feature" [label="the feature itself"];
    "New?" -> "Fold into the feature's single description" [label="a refinement/fix to it"];
    "Is it a bug FIX?" -> "Did the BROKEN behavior ship in the previous release?" [label="yes"];
    "Is it a bug FIX?" -> "List as a New Feature" [label="no, it's an enhancement"];
    "Did the BROKEN behavior ship in the previous release?" -> "List as a Bug Fix" [label="yes"];
    "Did the BROKEN behavior ship in the previous release?" -> "Drop it (user never saw it)" [label="no"];
}

To answer "did it exist in the previous release," read the previous release's own notes (CHANGELOG entry for the last tag) — not the current branch.

Output recipe

Group by impact, then by kind. Drop everything trivial or internal.

## 🚀 New Features
### Major      — headline; the reasons someone updates
### Moderate   — visible, welcome, not headline

## 🐞 Bug Fixes   (only behavior that shipped broken in the previous release)
### Major      — crashes, hangs, data loss, wrong results
### Moderate   — visible glitches, papercuts

Rules for the body:

• Lead with the headline. The first Major feature is why the release exists.
• User-facing voice. "Recover Codex side chats as searchable rows," not "fix: async cache side chat discovery."
• One line per delta, collapsing all the commits behind it.
• Name new providers/agents and what they unlock.

Always drop (never user-facing)

• Internal cleanup, refactors, dead-code removal, renames of internal symbols
• Test additions/hardening, fixture updates, CI, merge commits
• Pre-release stabilization and "fixed what we just built this cycle"
• Dev-cycle redesigns/polish of a feature that is new this release
• Anything whose only audience is the developer

Worked example (the failure this skill encodes)

Cycle shipped a brand-new Session Runway feature. The git log held ~15 commits: add per-agent Claude runway, move runway controls into toolbar pills, refine runway controls, runway bars scale relatively, stabilize runway row presence, prefer Claude Desktop titles, etc.

Wrong (journey): a "Session Runway" feature bullet plus a separate "Quota Meter toolbar redesign" feature plus bug-fix lines for "bars no longer render full-width," "rows appear before samples," "row presence stabilized."

Right (destination): one bullet —

Session Runway — live per-session burn-rate bars showing which active Codex and Claude sessions are eating your plan and how long until reset.

The toolbar, the bars, the row behavior were never separate user experiences; they are how Session Runway ships. Zero bug-fix lines, because no user ever had the broken intermediate versions.