Aicr Release Notes

AICR Release Notes Draft

Generates the user-facing release notes summary that goes into the GitHub Releases body (e.g. https://github.com/NVIDIA/aicr/releases/tag/v0.13.0), NOT the raw tools/changelog commit list that already appears below the summary. Output is a draft — the author hand-edits before publishing.

When to Use

• User asks to draft release notes, release summary, or release announcement
• User invokes /aicr-release-notes
• A tag is about to be cut and the maintainer needs the highlights paragraph

Do NOT use this skill to publish a release, push a tag, or edit CHANGELOG.md. It only writes a Markdown draft to a temp file.

Inputs

tools/changelog is the single source of truth for:

• Which tag range is being summarized (it picks the latest stable tag and prints [MSG] Changes since vX.Y.Z to stderr).
• The set of commits to consider.
• The author handle for every commit (already rendered as by [@handle](https://github.com/handle) at the end of each line).

Do NOT re-derive any of this with separate git log, gh api, or gh pr list calls. If tools/changelog doesn't surface it, it doesn't belong in the summary.

No optional input is needed. Do not ask for or guess the target tag — the filename is fixed (see Step 5) and the body never names the new tag (GitHub renders the tag in the release header).

Procedure

Step 1 — Gather raw material

Run in parallel:

# Commit list since last stable tag — single source of truth
tools/changelog

# Previous release body for style mirroring (use the tag from
# tools/changelog's "[MSG] Changes since vX.Y.Z" stderr line)
gh release view <previous-tag> --json body --jq '.body'

If tools/changelog errors ("No release tags found", empty output), stop and ask the user how to proceed — do not invent a range.

Step 2 — Classify commits into themes

Read every line of tools/changelog output. Group by user-visible impact, NOT by conventional-commit scope. The goal is a release-notes narrative, not a mirror of git log. Useful theme buckets, in rough priority order:

1. Headline feature — the single most significant new capability (often a new command, a new deployer, a new contract). Open paragraph should name 3–4 of these inline as bolded phrases.
2. New deployer / output target — bundler additions, new packaging.
3. Recipes & overlays — new accelerator/service/intent combinations, new mixins. Use a bulleted sub-list when there are 3+.
4. Validation / evidence / supply chain — anything that strengthens trust: BOM, SBOM, signing, evidence verification, conformance.
5. Docs / DX — new doc site features, CLI ergonomics, config unification.
6. Other improvements — collect leftover user-visible wins.

Exclude from the narrative (they still appear in the raw changelog below the summary on the GitHub release page):

• deps: bumps and Renovate/Dependabot lines
• CI plumbing that doesn't change developer experience
• Pure refactors with no user-visible effect UNLESS the cumulative effect is a public API surface change worth flagging (e.g. "Per-Builder DataProvider isolation" got a mention because it's a contract change for embedders of pkg/client/v1 / pkg/aicr)
• Test-only changes
• Doc-style fixups

Step 3 — Draft the Markdown

Match the exact structure of the previous release. Required sections, in order:

1. Opening paragraph — one sentence. "This release focuses on …, …, …, and …." Each major theme is **bolded** inline. No heading above it.
2. ### Highlights — heading exactly as written.
3. **Theme Name** blocks — each starts with bolded title, em dash (—, with spaces), then 1–3 sentences OR a bulleted sub-list. Use sub-lists when enumerating 3+ concrete items (e.g. recipes added).
4. ### Deprecations — required whenever the release deprecates or removes anything on the four frozen surfaces (CLI, REST, Go SDK, bundle and artifact schemas); omit the heading entirely when it does not. One bullet per item: what is deprecated, the replacement, and the release that removes it. This is a release-blocking section, not a courtesy — see the deprecation policy. Every bullet here must also have an entry in docs/user/deprecations.md; if it does not, the deprecation is incomplete and the release is not ready.
5. Closing credits line — ***Thanks to*** @user1, @user2, …, and @mchmarny. Alphabetical (case-insensitive) by handle, with @mchmarny moved to the final position preceded by and .

Style rules drawn from prior releases:

• Issue/PR references use [NVIDIA/aicr#NNN](https://github.com/NVIDIA/aicr/issues/NNN) form, NOT a bare #NNN.
• External product links use full URLs in markdown ([docs.nvidia.com/aicr](https://docs.nvidia.com/aicr)).
• Backtick CLI commands: `aicr validate`, `aicr evidence verify`.
• Use em dashes (—) not hyphens for the inline definition pattern.
• No emoji. No "What's Changed" heading. No version-comparison link (GitHub adds those automatically).
• Keep total length comparable to the previous release (~250–400 words in the summary, not counting the auto-appended changelog).