pixelheros/CCGS Skill Testing Framework/skills/sprint/patch-notes.md

Skill Test Spec: /patch-notes

Skill Summary

/patch-notes is a Haiku-tier skill that generates player-facing patch notes from existing changelog content, stripping internal task IDs and technical jargon in favor of plain language. It filters entries to only those relevant to players (visible features and bug fixes; internal refactors are excluded). No director gates are used. The skill asks "May I write to docs/patch-notes-vX.X.md?" before persisting. Verdict is always COMPLETE.

---

Static Assertions (Structural)

Verified automatically by /skill-test static — no fixture needed.

• Has required frontmatter fields: name, description, argument-hint, user-invocable, allowed-tools
• Has ≥2 phase headings
• Contains verdict keyword: COMPLETE
• Contains "May I write" language (skill writes patch notes file)
• Has a next-step handoff (e.g., share with community manager)

---

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 exists with 5 entries:
  • "Add dual-wield melee system" (Features — player-facing)
  • "Fix crash on level transition" (Fixes — player-facing)
  • "Add enemy patrol AI" (Features — player-facing)
  • "Refactor input handler to use event bus" (Fixes — internal only)
  • "Update dependency: Godot 4.6" (internal only)
• Version is v0.4.0

Input: /patch-notes v0.4.0

Expected behavior:

1. Skill reads docs/CHANGELOG.md
2. Skill filters to 3 player-facing entries; excludes 2 internal entries
3. Skill rewrites entries in plain language (no task IDs, no tech jargon)
4. Skill presents draft to user
5. Skill asks "May I write to docs/patch-notes-v0.4.0.md?"
6. User approves; file written; verdict COMPLETE

Assertions:

• Only 3 entries appear in the patch notes (2 internal entries excluded)
• Entries are written in plain language without internal task IDs
• File path matches docs/patch-notes-v0.4.0.md
• "May I write" prompt appears before file write
• Verdict is COMPLETE after write

---

Case 2: No Changelog Found — Directed to run /changelog first

Fixture:

• docs/CHANGELOG.md does NOT exist

Input: /patch-notes v0.4.0

Expected behavior:

1. Skill attempts to read docs/CHANGELOG.md — not found
2. Skill outputs: "No changelog found — run /changelog first to generate one"
3. No patch notes are generated; no file is written

Assertions:

• Skill does not crash when changelog is absent
• Output explicitly directs user to run /changelog
• No "May I write" prompt appears (nothing to write)
• Verdict is BLOCKED (dependency not met)

---

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

Fixture:

• docs/CHANGELOG.md exists with player-facing entries
• design/community/tone-guide.md exists with guidance: "upbeat, encouraging tone; avoid passive voice"

Input: /patch-notes v0.4.0

Expected behavior:

1. Skill reads changelog
2. Skill detects tone guide at design/community/tone-guide.md
3. Skill applies tone guidance when rewriting entries in plain language
4. Patch notes use upbeat, active-voice phrasing
5. Skill presents draft, asks to write, writes on approval

Assertions:

• Skill checks design/ for a community or tone guidance file
• Tone guide content influences phrasing of patch note entries
• Output reflects active voice and upbeat tone where applicable
• Skill notes that tone guidance was applied

---

Case 4: Patch Note Template Exists — Used instead of generated structure

Fixture:

• .claude/docs/templates/patch-notes-template.md exists with a structured header format
• docs/CHANGELOG.md exists with player-facing entries

Input: /patch-notes v0.4.0

Expected behavior:

1. Skill reads changelog and detects template exists
2. Skill populates the template with player-facing entries
3. Template header/footer structure is preserved in the output
4. Skill asks "May I write" and writes on approval

Assertions:

• Skill checks for a patch notes template before generating from scratch
• Template structure is used when found (not overridden by default format)
• Player-facing entries are inserted into the correct template section
• Output note confirms template was used

---

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

Fixture:

• docs/CHANGELOG.md exists with player-facing entries
• review-mode.txt contains full

Input: /patch-notes v0.4.0

Expected behavior:

1. Skill compiles patch notes in full mode
2. No director gate is invoked (community review is a separate, manual step)
3. Skill runs on Haiku model — fast compilation
4. Skill notes in output: "Consider sharing draft with community manager before publishing"
5. Skill asks user for approval and writes on confirmation

Assertions:

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

---

Protocol Compliance

• Reads docs/CHANGELOG.md before generating patch notes
• Filters entries to player-facing items only
• Rewrites entries in plain language without internal IDs
• Always asks "May I write" before writing patch notes file
• No director gates are invoked
• Runs on Haiku model tier (fast, low-cost)

---

Coverage Notes

• The case where all changelog entries are internal (zero player-facing items) is not tested; behavior is an empty patch notes draft with a warning.
• Version number parsing from the changelog header is an implementation detail not verified here.
• The community manager consultation noted in Case 5 is advisory; a separate skill or manual review handles that step.