/patch-notes

name: patch-notes
description: "Player-facing patch notes from git history and changelogs. Translates developer language into player communication."
argument-hint: "[version] [--style brief|detailed|full]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash(bash "*/.claude/skills/patch-notes/../../hooks/yaml-helper.sh" resolve_config *), Bash(git log *)
model: sonnet

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation`

**Automation mode**: Resolve `modes.automation` (`project.local.yaml` → `project.yaml` → default `collaborative`). Every `AskUserQuestion` call and every file write follows `.claude/docs/automation-modes.md` (collaborative asks always · guided major-only · autonomous logs and proceeds; `automation_always_ask` categories always prompt).

Patch Notes

Provenance check — before reading any history

**Confirm the history you are about to read belongs to THIS game.** Run this before Phase 2 and stop if it fails.

1. Sample the recent log: `git log --oneline -20`. **If it is empty or git is unavailable, skip this check** — there is nothing to classify, and Phase 2's no-changelog-data branch is the right stop. 2. **Classify every commit in the range, one at a time**, into exactly one of:

• **Game** — changes the game the player plays: mechanics, content, balance,

art, audio, UI, a bug in any of those.

• **Framework / maintenance** — changes Claude Code Game Studios itself or the project's tooling:

subjects naming skills, hooks, agents, the test plan, CI, the framework's own docs. **Excluded from player-facing notes, but not a reason to stop.**

• **Unclear** — treat as framework. A commit you cannot confidently place is

not one to write player copy from. 3. Then decide from the counts:

• **At least one Game commit** → proceed, using **only** those. Say how many

of how many you used, so the reader can see the filter ran.

• **Zero Game commits** → stop, using the message below, and give the count (0 of how many) so the reader can see the filter ran.

> **Filter per commit; do not stop on a repo that merely contains maintenance > work.** Every project built on this framework accumulates commits touching > hooks, CI and skills — the game repo *is* the framework repo, so a repo-level > stop fires on virtually every real project. The danger is not that such > commits *exist*; it is that they get **rendered as player-facing copy**. > Excluding them addresses that exactly, and a repo-level stop does not.

Corroborate before you proceed, cheaply: the Game commits should name systems that appear in `design/` and the code root (`src/`, `Assets/` or `Source/`). If they name a product those directories never mention, that is the real wrong-history signal — stop.

If **no** commit in the range is this game's, say so and stop:

> "The git history in this repo does not appear to belong to [game]: 0 of the [N] > recent commits are Game commits. The recent > commits describe [what they actually describe]. I cannot generate release notes > from it — point me at the right history, or supply the change list directly."

Verdict: **BLOCKED** — stop here without generating notes.

**Why this is a hard stop, not a warning.** Framework-internal commits rendered as player copy read as real changes: a session-hook timeout becomes *"Fixed an issue where progress from your last session could be lost on launch"* in a game with **no save system**. That copy is fluent, plausible, and entirely false. A reader cannot tell the difference; only this check can.

---

Phase 1: Parse Arguments

• `version`: the release version to generate notes for (e.g., `1.2.0`)
• `--style`: output style — `brief` (bullet points), `detailed` (with context), `full` (with developer commentary). Default: `detailed`.

If no version is provided, ask the user before proceeding.

---

Phase 2: Gather Change Data

• Read the version's entry in `docs/CHANGELOG.md`, the changelog `/write-changelog` writes, if it has one
• Run `git log` between the previous release tag and current tag/HEAD as a fallback
• Read sprint retrospectives in `production/sprints/` for context
• Read any balance change documents in `design/balance/`
• Read bug fix records from QA if available

**If no changelog data is available** (no `docs/CHANGELOG.md` entry for this version, and git log is empty or unavailable):

> "No changelog data found for [version]. Run `/write-changelog [version]` first to generate the > internal changelog, then re-run `/patch-notes [version]`."

Verdict: **BLOCKED** — stop here without generating notes.

---

Phase 2b: Detect Tone Guide and Template

**Tone guide detection** — before drafting notes, check for writing style guidance:

1. Check `.claude/docs/technical-preferences.md` for any "tone", "voice", or "style" fields or sections. 2. Check `docs/PATCH-NOTES-STYLE.md` if it exists. 3. Check `design/community/tone-guide.md` if it exists. 4. If any source contains tone/voice/style instructions, extract them and apply them to the language and framing of the generated notes. 5. If no tone guidance is found anywhere, default to: player-friendly, non-technical language; enthusiastic but not hyperbolic; focus on what the player experiences, not what the developer changed.

**Template detection** — check whether a patch notes template exists:

1. Glob for `docs/patch-notes-template.md` and `.claude/docs/templates/patch-notes-template.md`. 2. If found at either location, read it and use it as the output structure for Phase 4 instead of the built-in style templates (Brief / Detailed / Full). Fill in the template's sections with the categorized data, mapping each category to the template section that means the same (New Content → its new-features section, Bug Fixes → its fixes section); a category with no matching section goes under the closest one, never dropped. Keep the template's header and footer tex