necmttn/ax/release-announcement

ax:release-announcement

Write release announcements that are grounded in the actual release range and the agent sessions that produced it. This skill owns the curated layer under docs/releases/; Release Please still owns CHANGELOG.md.

Assumes ax is on PATH and the local ax database is reachable. If ax fails with a DB connection error, tell the user to start the repo DB and continue from git evidence only if they ask.

When to fire

Use this skill for:

• "write release notes" / "draft release announcement"
• "prepare changelog" / "update the website changelog"
• "release page" / "version page" / "SEO release page"
• "what changed in vX.Y.Z"
• "generate announcement for vX.Y.Z"
• "explain how we got to this release"

Do not use this for a single commit message, generic README edits, or a non-release feature doc.

Workflow

1. Resolve the version and range

If the version is known:

bun run release:announcement -- X.Y.Z

This drafts docs/releases/vX.Y.Z.md and, when the Release Please compare heading is present, embeds:

• previous release tag (BASE_REF)
• release tag or HEAD (HEAD_REF)
• git diff --name-status "$BASE_REF..$HEAD_REF"
• git log --reverse --format='%h %cs %s' "$BASE_REF..$HEAD_REF"

If you need to inspect manually:

BASE_REF=<previous-release-tag>
HEAD_REF=<release-head-or-tag>
git diff --name-status "$BASE_REF..$HEAD_REF"
git log --reverse --format='%h %cs %s' "$BASE_REF..$HEAD_REF"

2. Map commits and files to agent sessions

Use the file list to identify touched subsystems. Use the commit list to pick important SHAs. Then query ax:

ax ingest here --since=30d
ax sessions here --days=30
ax sessions near <important-sha>
ax recall "<subsystem or decision>" --sources=turn,commit --scope=here

For large releases, inspect at least:

• one SHA per major topic
• one SHA near each major schema/API/CLI change
• any SHA tied to a surprising bug fix or reversal
• session windows around the merge/release PR if available

3. Write the announcement

Replace the generated draft with a topical narrative. Keep it concise, but make it useful:

• How we got here - the problem, decision tree, tradeoffs, and why the

final shape won. Cite session/commit evidence in prose.

• What changed - grouped by topic, not one flat commit list.
• Example - a CLI command, config snippet, output sample, schema fragment,

or before/after workflow when the release changes behavior.

• Visual evidence - screenshot, diagram, or output capture when a UI, CLI,

dashboard, TUI, or workflow is easier to understand visually.

• Why it matters - the practical day-to-day impact.

Do not invent motivation. If ax session evidence is missing, say what the commits and changed files prove and keep the story narrower.

4. Assets and rendering

Put website-visible release images here:

apps/site/public/releases/assets/

Reference them from release markdown:

![Focused release screenshot](/releases/assets/vX.Y.Z-topic.png)

The website release renderer supports headings, lists, links, bold scopes, fenced code blocks, and images. Use those instead of hand-written HTML.

5. Verify

Run:

bun run typecheck
cd site && bun run build

If the page changed, preview and smoke the specific version page:

cd site
bun run preview -- --host 127.0.0.1 --port 4175

Check /changelog and /changelog/vX.Y.Z.