mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios.git
synced 2026-10-16 10:17:06 +00:00
DonchitosandClaude Opus 5.5
b21fa0f7f2
Fix release for 1.1.1: the minimal path end to end, engine commands that run on Godot, Unity and Unreal, hook warnings you can see, and verdicts that say when they could not check. Details in CHANGELOG.md; upgrade steps in UPGRADING.md (v1.1.1 → v1.1.2). Fixes #67 Fixes #131 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WuJn2FdynEybfL5KC697nJ
262 lines
12 KiB
Markdown
262 lines
12 KiB
Markdown
# 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.
|