release-notes

name	release-notes
description	Use when preparing a release, drafting human-readable release notes, or distilling a CHANGELOG range into a categorized impact summary. Trigger on "draft release notes for 3.1.0", "what's the user-impact summary of these commits", "summarize what changed since v3.0.5", "write the announcement for the 3.0 release". Reads the git-chglog-generated CHANGELOG.md and the underlying commit range, classifies each change by impact category (breaking, schema, feature, fix, perf, internal), and produces a structured human-readable document. Complements but does not replace the mechanical CHANGELOG (the chglog output is the canonical changelog; this skill produces the announcement-style narrative for users). Does NOT modify CHANGELOG.md (that's `pixi run update-changelog`'s job) or .chglog/config.yml (protected).
allowed-tools	Read, Glob, Grep, Bash

Release notes for Lancet2

Lancet2 has two layers of release-time documentation:

1. CHANGELOG.md — generated by git-chglog from the conventional-commit messages. Mechanical, complete, organized into four sections that the project's .chglog/config.yml defines via title_maps: feat → New Features, fix → Bug Fixes, perf → Performance Improvements, chore → Refactoring. Other commit types (refactor:, docs:, build:, test:, etc.) parse but are silently dropped from the changelog because they are not in the filter list. Lives in repo root, regenerated by pixi run update-changelog. The canonical record.
2. Release notes / announcement — human-readable, user-impact-organized, distills the CHANGELOG into "here's what matters for someone running the pipeline." Lives wherever the user announces the release (GitHub Release page, mailing list, blog post). Not auto-generated; this skill produces the draft.

The two are complementary. CHANGELOG.md is for downstream maintainers tracking every change; release notes are for users deciding whether to upgrade.

Step 1 — Establish the commit range

The release notes cover everything from the previous tag to the new tag (or HEAD if not yet tagged). Confirm with the user:

git log --oneline v3.0.5..HEAD | head -30

If the previous tag is v3.0.5 and the new release is v3.1.0, that's the range. The user may want a different range (e.g., "since the start of the year") — accept their range and use it for everything below.

Step 2 — Read the chglog-generated section

If the user has already run pixi run update-changelog, the new entries are at the top of CHANGELOG.md. Read them. The chglog output groups by the four conventional-commit types the filter accepts — New Features (feat), Bug Fixes (fix), Performance Improvements (perf), and Refactoring (chore).

If the user has NOT yet run update-changelog, suggest running it first so the categorization is mechanical. The skill operates on the chglog output, not on raw commit messages directly.

Step 3 — Reclassify by user impact

The chglog categorization is by commit type. The release notes categorization is by user impact, which is different. Walk every entry and assign it to one of the impact categories below:

1. Breaking changes — anything that requires user action to upgrade. CLI flag renames or removals, output format changes, default value changes that affect existing pipelines, removed features. ALL breaking changes lead the release notes; nothing else is more important.

2. Schema changes — additions, renames, or semantic updates to FORMAT/INFO/FILTER fields in the VCF output, or to the probe-tracking TSV format. Even non-breaking schema additions (a new FORMAT field) deserve their own category because downstream consumers may want to start using them.

3. New features — new capabilities the user can now use. New CLI flags (additive), new pipeline stages, new analysis modes. The "what's new" section.

4. Bug fixes — corrections to existing behavior. Group by area: caller, graph, I/O, CLI. Mention impact ("fixes a crash when ...") not just the change ("fixes Genotyper::EvaluateAllele").

5. Performance improvements — measurable wall-clock or memory improvements. Cite the numbers from the commit body ("graph builder 12% faster on chr1") if available.

6. Internal / contributor-facing changes — refactors, documentation rewrites, build-system improvements, lint-tool changes. Mention briefly; users don't read this section closely but maintainers and contributors do.

A single commit may belong to multiple impact categories (a feat: that adds a new flag AND deprecates an old one is both Feature and Breaking). When in doubt, surface in the higher-impact category.

Step 4 — Draft the release notes

Use a consistent structure:

# Lancet2 v3.1.0

Release date: <date>.
Compared with v3.0.5: <N commits, summary of breadth>.

## Breaking changes

(One bullet per breaking change. Include the migration guidance for each
— "if you used --flag X, switch to --flag Y" or "the FORMAT/SB field
has been renamed to FORMAT/SBLOR; consumers should update.")

## Schema changes

(VCF and TSV format changes. Each entry: what changed, what downstream
consumers should do, a pointer to the relevant docs/guides/ file.)

## New features

(Headline features first. For each: a one-paragraph description and
the relevant documentation pointer. Aim for 3-5 paragraphs total —
release notes are for skimming.)

## Bug fixes

(Group by area. Use compact bullet lists; details belong in the
chglog. Cite issue/PR numbers where available.)

## Performance improvements

(Each entry: what was optimized, the measured improvement, the
typical workload it affects.)

## Internal changes

(Brief summary, not exhaustive. "X commits of refactoring in the
core layer", "Build system migrated to Y", etc.)

## Upgrading

(Concrete commands or steps. If there are no breaking changes, this
is one sentence: "Drop-in replacement; no action required." If there
are breaking changes, this is a step-by-step migration recipe.)

## Acknowledgements

(Contributor list if applicable. Lancet2 is a NYGC project; this
section can credit specific external contributors who landed work
in the release range.)

Step 5 — Cross-validate with the actual code

Before finalizing the release notes, sanity-check the high-impact claims against the source:

• For every breaking change, confirm the breakage is real by looking at the affected file. A claim that "FORMAT/SB has been renamed" but the source still emits SB is wrong.
• For every performance claim, confirm the numbers are in the commit body and represent the right workload (chr1 vs chr4, germline vs somatic, full-region vs _REGION_SMALL).
• For every documentation pointer, confirm the doc exists and covers what the release notes claim.

This step catches the most common error: the user wrote release notes from memory or from a draft, and the actual landed code is slightly different.

Step 6 — Hand off to the user

Release notes are user-published artifacts. The skill produces the draft; the user reviews, edits the tone (Lancet2 might want a more formal voice than the draft style above), and publishes. Save the draft to notes/release-<version>.md for the user to finalize and copy into their release tooling.

Do NOT commit the release notes file to the repo. CHANGELOG.md is the in-repo record; release notes belong in the release platform (GitHub Releases, etc.).

When NOT to use this skill

Do not use this skill for:

• Generating CHANGELOG.md itself — that's pixi run update-changelog which calls scripts/update_changelog.sh which calls git-chglog. CHANGELOG generation is fully mechanical.
• Editing .chglog/config.yml or .chglog/CHANGELOG.tpl.md (both protected). Changes there reshape the mechanical output and go through normal review.
• Drafting commit messages — that's the agent's responsibility on every commit, not a release-time activity.

When the release contains a breaking change

Pause and confirm with the user that the breakage is intentional and the migration story is solid. Breaking changes are the most dangerous release content — a poorly-explained breaking change burns trust. The release notes should include:

• A clear "this will break for you if X" sentence.
• A concrete "to upgrade, do Y" recipe.
• A justification for why the break was necessary (deprecation period if there was one, alternative considered, downstream-impact assessment).

If the user can't articulate any of these, suggest holding the breaking change for a future release where the migration story is clearer.