release-notes

name	release-notes
description	Drafts FRB1 release notes from commits/PRs since the last release. Triggers: cutting an FRB1 release, drafting release notes, /release-notes.

FRB1 Release Notes

Drafts the release notes markdown from git history since the previous release. Does not bump versions, trigger workflows, or publish the release — that's [[release]]. Only writes the draft.

Modeled on the Gum repo's gum-monthly-release skill (same hybrid curated + full changelog format, same fan-out-to-avoid-summarization fix), adapted for one structural difference: FRB1's history is not PR-only. A recent 3.5-month window had 88 commits but only 16 carried a (#N) PR suffix — the rest are direct commits, mostly by vchelaru. So commits, not PRs, are the canonical unit here; PR numbers are used opportunistically for the ~15-20% that have one, not as the primary iteration axis.

Ask first, don't guess

Same collaboration stance as Gum's skill: when categorization, intent, or which commits belong together is unclear, stop and ask, or drop it in ## Open Questions. Don't invent user-impact descriptions from a one-line commit message.

Step 1: Front-loaded questions

Ask up front, one message, numbered:

1. Release tag. Recent convention: Release_<Month>_<DD>_<YYYY> (e.g. Release_September_23_2025) — some older tags drop the Release_ prefix, ignore those as precedent.
2. Previous-release boundary. Propose the most recent tag from gh release list --repo vchelaru/FlatRedBall --limit 5 and confirm. Cross-check it: if a newer published release exists between the proposed boundary and main, flag it before proceeding (using a stale boundary double-counts commits already shipped).
3. Breaking changes this release? If yes, get the explanation now (no separate migration-doc convention confirmed for FRB1 yet — ask the user how they want it described, don't assume a doc URL pattern exists).

Step 2: Gather commits

The canonical set is every commit between the boundary tag and main, not a PR search:

git fetch origin --tags -q
git log --no-merges <prev-tag>..origin/NetStandard --format="%H|%an|%s"

For the ~15-20% of subjects ending in (#N), that's a real PR — gh pr view N --repo vchelaru/FlatRedBall --json title,body,author,files gets richer context if the subject alone is too sparse. For the rest, there is no PR to look up; read the commit itself (git show <hash>) for diff context when the subject line alone doesn't say enough.

No proven noise-filter list exists for FRB1 yet (unlike Gum's GITBOOK-/FRB fixes exclusions, which came from repeated real drafts). Don't invent exclusion patterns — if a commit looks like repo housekeeping (version bumps, merge artifacts, CI-only), flag it in Open Questions rather than silently dropping it or silently keeping it.

Step 3: Fan out per-commit-batch expansion to parallel subagents

Same structural fix as Gum's skill, adapted to commits: the main agent never reads the full commit list itself. Batch the canonical commit set into groups of ~8-10, spawn one subagent per batch in parallel, each returning finished user-impact bullets for its batch.

The FRB1-specific judgment call, different from Gum's PRs-only case: since commits (not PRs) are the unit, a run of several small sequential commits often builds one feature incrementally (e.g. "First pass at collision fixes" → "Improved camera controlling entity to properly use padding..." → "Handle passing back and forth now works"). The subagent should consolidate adjacent same-theme commits into one bullet when they clearly form a single unit of work, and keep them separate when they're genuinely distinct changes that happen to be adjacent in history. This cuts both ways versus Gum's rule (which only ever expands a roll-up PR into more bullets, never consolidates) — judge each batch on its own merits.

Subagent prompt should cover: the batch's commit hashes+subjects+authors, instruction to run git show <hash> for any commit whose subject doesn't already say what changed, the consolidate-vs-separate judgment above, and the same user-impact-first clarity bar as Step 5 below. Return one JSON object per resulting bullet: { "commits": ["<hash>", ...], "author": "name", "section": "...", "bullet": "...", "confidence": "high"|"medium"|"low", "note": "..." }.

Step 4: Categorize

Recurring sections seen in past releases (confirm against a couple of gh release view <recent-tag> calls before drafting, since this list isn't guaranteed exhaustive):

1. Breaking Changes — omit if none.
2. Biggest Changes — only for genuinely standout releases (some releases have none at all — e.g. June/March 2025 skipped it entirely). Don't force it.
3. FRB Editor — Glue/editor-side changes.
4. Edit Mode — live-edit-specific changes (seen in at least one release, often absent).
5. FRB Engine and Code-related — runtime engine changes.
6. Other sections as the actual content warrants — these aren't a fixed enum, they're what past releases happened to need. Omit any section with nothing in it.
7. What's Changed — complete per-commit list, see Step 6.
8. Full Changelog — placeholder, see Step 6.

Attribution: default primary author is vchelaru (79 of 88 commits in the sampled window) — no (thanks @...) for their own commits. Everyone else gets (thanks @author), matching the trailing-space style already used in past releases ((thanks @vicdotexe )).

Step 5: Self-review for clarity (mandatory before writing)

Same bar as Gum's skill — re-read every bullet as a user who's never seen the codebase:

• Names the user-visible symptom/capability/scenario, not internal class/method names.
• Fixes state the symptom and trigger condition, not just "fixed a bug."
• Features name the scenario the user can now do, not the API added.
• If you can't defend a bullet in a code review, investigate further, move it to Open Questions, or drop it as internal-only.

Step 6: What's Changed + Full Changelog

Below the curated sections, list every commit in the canonical set (newest first), one line each, for verifiability:

git log --no-merges <prev-tag>..origin/NetStandard --format="- %s (thanks @author, only if not vchelaru)"

Then a placeholder line directly after:

PLACEHOLDER!!!! Full Changelog link

This is https://github.com/vchelaru/FlatRedBall/compare/<prev-tag>...<new-tag> — only resolvable once the new tag exists, filled in after the release is cut, not missing content.

Use the same loud plain-text placeholder style for any spotlight-feature images in Biggest Changes: PLACEHOLDER!!!! IMAGE/GIF for <feature name>.

Step 7: Write, open, walk through Open Questions

Write to temp/release-notes-YYYY-MM-DD.md at the repo root (date from the release tag), then open it (start temp/release-notes-YYYY-MM-DD.md) and confirm the path in chat.

Work through ## Open Questions one at a time with the user, editing the file directly as each resolves. The skill is done when the file has only the release notes - no Open Questions block left.

Related

• [[release]] — the rest of the release pipeline (version bump, workflow triggers, actually cutting the tag and publishing). This skill only produces the notes draft that feeds into that pipeline's release-creation step.