Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/sprint/patch-notes.md

Skill Test Spec: /patch-notes

Skill Summary

/patch-notes is a Sonnet-tier skill that turns a release's changes into player-facing patch notes. Before reading any history it classifies recent commits as Game or Framework / maintenance (Unclear counts as Framework), uses only the Game commits, and says how many of how many it used. It gathers change data from production/releases/[version]/changelog.md, the version's entry in docs/CHANGELOG.md, and — as a fallback — git log from the previous release tag. It checks for a tone guide (.claude/docs/technical-preferences.md, docs/PATCH-NOTES-STYLE.md, design/community/tone-guide.md) and a patch-notes template (docs/patch-notes-template.md, .claude/docs/templates/patch-notes-template.md), removes internal-only changes, and translates the rest into player language in Brief, Detailed (default) or Full style — or in the template's structure when one exists, saying which template it used. No director gates are used. The skill asks "May I write these patch notes to docs/patch-notes/[version].md, and an archive copy to production/releases/[version]/patch-notes.md?" — naming both files — and on approval writes both. Verdicts: COMPLETE (notes generated and saved) or BLOCKED (no changelog data and no git history, or no Game commit in the history).

---

Static Assertions (Structural)

Checked against the SKILL.md by /skill-test spec — no fixture needed.

• Has required frontmatter fields: name, description, argument-hint, user-invocable, allowed-tools
• Has ≥2 phase headings
• Contains verdict keywords: COMPLETE, BLOCKED
• Contains "May I write" language (skill writes patch notes file)
• Has a next-step handoff (/release-checklist, community-manager tone review)

---

Director Gate Checks

None. Patch notes generation is a fast compilation task; no gates are invoked.

---

Test Cases

Case 1: Happy Path — Changelog filtered to player-facing entries

Fixture:

• docs/CHANGELOG.md has a v0.4.0 entry with 5 items:
  • "Add dual-wield melee system" (player-facing)
  • "Fix crash on level transition" (player-facing)
  • "Add enemy patrol AI" (player-facing)
  • "Refactor input handler to use event bus" (internal only)
  • "Update dependency: Godot 4.6" (internal only)
• Git history since the previous tag holds the Game commits behind those items
• No tone guide and no patch-notes template exist

Input: /patch-notes v0.4.0

Expected behavior:

1. Skill classifies the recent commits and says how many of how many it used
2. Skill reads the v0.4.0 entry in docs/CHANGELOG.md
3. No tone guide is found, so the default tone applies; no template is found, so the built-in Detailed style (the default --style) is used
4. Skill keeps the 3 player-facing items and removes the 2 internal ones
5. Skill rewrites the items in player language (no task IDs, no internal system names)
6. Skill presents the notes with a count of changes by category and the list of excluded internal changes
7. Skill asks "May I write these patch notes to docs/patch-notes/v0.4.0.md, and an archive copy to production/releases/v0.4.0/patch-notes.md?"
8. User approves; both files are written; verdict COMPLETE

Assertions:

• Only the 3 player-facing items appear in the notes; the 2 internal items are listed separately as excluded, for review
• Entries are written in plain language without internal task IDs or system names
• Notes use the built-in Detailed style (Highlights, New Content, … Known Issues) — the default when no --style is given and no template exists
• "May I write" prompt naming docs/patch-notes/v0.4.0.md appears before any file is written
• Verdict is COMPLETE after the write

---

Case 2: No Changelog File — Falls back to git history

Fixture:

• Neither production/releases/v0.4.0/changelog.md nor docs/CHANGELOG.md exists
• Tag v0.3.0 exists; the range v0.3.0..HEAD holds 6 Game commits and 2 Framework / maintenance commits (one touching a hook, one touching CI)

Input: /patch-notes v0.4.0

Expected behavior:

1. Skill classifies the commits, keeps the Game commits, excludes the 2 framework commits, and says how many of how many it used
2. Skill finds no changelog source and uses git log from v0.3.0 to HEAD as the fallback
3. Skill does NOT stop with BLOCKED — the "No changelog data found … Run /changelog [version] first" path requires the git history to be empty or unavailable as well
4. Skill generates notes from the Game commits only
5. Skill asks "May I write" before writing

Assertions:

• Skill does not crash and does not stop with BLOCKED while git history is available
• Skill falls back to git log from the previous tag (v0.3.0) to HEAD
• Output states how many of how many commits were used
• The 2 framework / maintenance commits do not appear in the patch notes
• "May I write" prompt appears before any file is written

---

Case 3: Tone Guidance from Design Folder — Incorporated into output

Fixture:

• docs/CHANGELOG.md has a v0.4.0 entry with player-facing items; git history holds the matching Game commits
• design/community/tone-guide.md exists with guidance: "upbeat, encouraging tone; avoid passive voice"
• docs/PATCH-NOTES-STYLE.md does not exist and .claude/docs/technical-preferences.md has no tone, voice or style fields
• No patch-notes template exists

Input: /patch-notes v0.4.0

Expected behavior:

1. Skill reads the changelog entry
2. Skill checks the three tone sources and finds design/community/tone-guide.md
3. Skill extracts the guide's instructions and applies them to the language and framing of the notes, in place of the built-in default tone
4. Structure stays the built-in Detailed style
5. Skill presents the notes, asks "May I write", writes on approval

Assertions:

• Skill checks the tone sources in Phase 2b, including design/community/tone-guide.md
• The tone guide's instructions are applied in place of the built-in default tone
• Entries use active voice ("Fixed a crash when…", "You can now…"), not passive ("A crash was fixed")
• Tone guidance changes wording only — the output structure is still the Detailed style

---

Case 4: Patch Note Template Exists — Used instead of the built-in styles

Fixture:

• .claude/docs/templates/patch-notes-template.md exists with a header block, the sections ## New, ## Fixed and ## Known Issues, and a footer
• docs/CHANGELOG.md has a v0.4.0 entry with one new feature and one bug fix, both player-facing; git history holds the matching Game commits

Input: /patch-notes v0.4.0 --style full

Expected behavior:

1. Skill globs docs/patch-notes-template.md and .claude/docs/templates/patch-notes-template.md; finds and reads the second
2. Skill uses the template as the output structure instead of the built-in Brief / Detailed / Full templates — even though --style full was passed
3. The new feature goes under ## New, the fix under ## Fixed
4. The template's header and footer are preserved
5. The output says the template was used and that it replaced --style full
6. Skill asks "May I write" and writes on approval

Assertions:

• Skill globs both template locations before generating
• The template's structure replaces the built-in style — no "Developer Commentary" section from the Full style despite --style full
• The new feature is placed under ## New and the fix under ## Fixed
• The template's header and footer are preserved in the output
• Output notes that .claude/docs/templates/patch-notes-template.md was used, and that it replaced the requested --style full

---

Case 5: Gate Compliance — No gate; community-manager is separate

Fixture:

• docs/CHANGELOG.md has a v0.4.0 entry with player-facing items; git history holds the matching Game commits
• project.yaml sets modes.review_mode: full

Input: /patch-notes v0.4.0

Expected behavior:

1. Skill compiles patch notes; no director gate is spawned (the skill resolves only automation, never review_mode)
2. Skill self-reviews the notes (Phase 5), then presents them and asks to write
3. Next steps suggest /release-checklist and sharing the draft with the community-manager for tone review before posting publicly
4. User approves; notes are written; verdict COMPLETE

Assertions:

• No director gate is invoked regardless of review mode
• Output suggests (but does not require) a community-manager tone review before posting
• Skill proceeds directly from compilation and self-review to the "May I write" prompt
• Verdict is COMPLETE

---

Case 6: Provenance Stop — Zero Game commits

Fixture:

• git log --oneline -20 shows 20 commits, all touching the framework or tooling — subjects such as "fix: session-start hook timeout", "docs: skill catalog", "ci: cache the test runner" — and none names a game system in design/ or the code root
• Neither production/releases/v0.4.0/changelog.md nor docs/CHANGELOG.md exists

Input: /patch-notes v0.4.0

Expected behavior:

1. Before Phase 2, skill classifies the sampled commits: 0 Game, 20 Framework / maintenance
2. Skill stops with "The git history in this repo does not appear to belong to [game] …", describing what the commits actually cover
3. No notes are generated and nothing is written; verdict BLOCKED

Assertions:

• Output names the classification result — 0 of 20 commits are Game commits
• Output contains the "does not appear to belong to" stop, not notes written from framework commits (no "Fixed an issue where …" line from a hook fix)
• No "May I write" prompt appears and no file is written
• Verdict is BLOCKED, not COMPLETE

---

Case 7: No Changelog Data — No changelog and no git history

Fixture:

• Neither production/releases/v0.4.0/changelog.md nor docs/CHANGELOG.md exists
• The project directory is not a git repository, so git log returns nothing

Input: /patch-notes v0.4.0

Expected behavior:

1. The sampled log is empty, so the provenance check is skipped — there is nothing to classify
2. Phase 2 finds no changelog source and no git history; skill outputs "No changelog data found for v0.4.0. Run /changelog v0.4.0 first to generate the internal changelog, then re-run /patch-notes v0.4.0."
3. Nothing is generated or written; verdict BLOCKED

Assertions:

• The "does not appear to belong to" provenance stop is NOT shown — an empty history is not a wrong history
• Output contains "No changelog data found for v0.4.0" and recommends /changelog v0.4.0
• No notes are generated, no "May I write" prompt appears, and no file is written
• Verdict is BLOCKED

---

Protocol Compliance

• Runs the provenance check before reading history, uses only Game commits, and says how many were used
• Reads the version's changelog entry (production/releases/[version]/changelog.md, docs/CHANGELOG.md) before falling back to git log
• Filters entries to player-facing items only, and lists the excluded internal changes for review
• Rewrites entries in plain language without internal IDs
• Always asks "May I write" before writing patch notes
• No director gates are invoked
• Declares model: sonnet — it writes player-facing copy

---

Coverage Notes

• A missing version argument (the skill asks before proceeding) is not tested.
• The case where all changelog entries are internal (zero player-facing items) is not tested.
• The community manager consultation noted in Case 5 is advisory; a separate skill or manual review handles that step.