171 lines
5.9 KiB
Markdown
171 lines
5.9 KiB
Markdown
# 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.
|