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 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.

1. New deployer / output target — bundler additions, new packaging.
2. Recipes & overlays — new accelerator/service/intent combinations,

new mixins. Use a bulleted sub-list when there are 3+.

1. Validation / evidence / supply chain — anything that strengthens

trust: BOM, SBOM, signing, evidence verification, conformance.

1. Docs / DX — new doc site features, CLI ergonomics, config

unification.

1. 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.

1. ### Highlights — heading exactly as written.
2. 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).

1. ### 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.

1. 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

form, NOT a bare #NNN.

• External product links use full URLs in markdown

(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).

Step 4 — Build the contributor list

The thanks line comes entirely from the by [@handle](...) annotations already present in tools/changelog output. Extract every unique @handle with a simple grep/awk over the changelog text:

tools/changelog 2>/dev/null \
  | grep -oE 'by \[@[^]]+\]' \
  | sed -E 's/by \[@//; s/\]$//' \
  | sort -uf \
  | grep -viE '\[bot$'

Note the [^]]+ capture stops at the FIRST ], so handles like dependabot[bot] come out as dependabot[bot (no trailing ]). The final grep -viE '\[bot$' accounts for this — do NOT change it to '\[bot\]$' or bots will leak into the thanks line.

Then:

• Drop any handle ending in [bot after extraction (bot accounts:

dependabot[bot], github-actions[bot], renovate[bot], copy-pr-bot, etc.).

• Sort alphabetically (case-insensitive).
• Move mchmarny to the final slot preceded by and .
• Do NOT link the @-mentions in the output — GitHub auto-links them.

Step 5 — Write the draft

Write to $TMPDIR/aicr-release-notes.md — fixed filename, no version suffix. Do NOT write under the repo tree — this is a hand-edit draft, not a checked-in artifact. Overwrite any prior draft at that path.

Append an "Unresolved questions for hand-edit" section at the bottom of the file, separated from the credits line by a horizontal rule (---). The author edits the file directly, so questions belong in the file, not in chat. Typical content:

• Calls the author should make about emphasis (e.g., "should the X

bump be promoted to a highlight?")

• Things to verify before publishing (issue references, feature

completeness, prior-release framing)

• Anything the skill chose to omit that the author may want back

Format the section as:

---

## Unresolved questions for hand-edit

1. **<topic>** — <one-or-two sentence note explaining the call to make>
2. **<topic>** — <…>

This section is for the author's eyes only and gets deleted before publishing.

After writing, print to chat:

1. A ready-to-run macOS clipboard command on its own line in a fenced

bash block: pbcopy < <absolute-path>. The user copies that line, runs it, and pastes into the GitHub release form. Do not print the bare path on a separate line — the pbcopy form is the path.

1. A one-line summary of which themes the draft surfaced (so the user

can quickly tell if you missed something).

Do NOT cat the full draft back into chat — the user will open the file directly. Do NOT print the unresolved questions separately — they are already in the file.

Output Format Reference

The structure to mirror, with placeholders:

This release focuses on <theme-1-bolded>, <theme-2-bolded>, <theme-3-bolded>, and <theme-4-bolded>.

### Highlights

**<Theme 1 Title>** — <1–3 sentence narrative explaining what shipped and
why it matters to a user. Reference commands in backticks. Link issues as
[NVIDIA/aicr#NNN](https://github.com/NVIDIA/aicr/issues/NNN).>

**<Theme 2 Title>** — <narrative>

**<Theme with enumerated items>**

* <Concrete item 1>
* <Concrete item 2>
* <Concrete item 3>

**Other Improvements**

* <Leftover user-visible win 1>
* <Leftover user-visible win 2>

**<Supply Chain or Trust Theme>** — <narrative>

***Thanks to*** @alice, @bob, @carol, and @mchmarny.

Failure Modes

• tools/changelog is empty — likely the tag already exists or

LAST_TAG..HEAD is empty. Ask the user which range to summarize.

• gh release view fails — the previous tag may not have a release

yet. Fall back to reading the README's recent-releases section or ask the user to point at a reference release for style.

• Repo state has uncommitted changes — fine, tools/changelog only

reads git history. No need to stash.

What This Skill Does NOT Do

• Does not run git tag or push tags
• Does not create the GitHub release
• Does not edit CHANGELOG.md or any in-repo file
• Does not re-derive commit ranges, author handles, or commit lists

outside of tools/changelog output