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

# Skill Test Spec: /changelog

## Skill Summary

`/changelog` is a Sonnet-tier skill that generates two changelogs — an internal
one and a player-facing one — from the git commits since the last release tag.
Before using the injected history it classifies every commit as Game or
Framework / maintenance (Unclear counts as Framework), uses only the Game
commits, and says how many of how many it used; with zero Game commits it stops.
With no history at all (not a git repository, or no commits) it skips that check
and stops at Phase 1. It reads sprint plans in `production/sprints/` and GDDs in
`design/gdd/` for context, and sorts changes into New Features, Improvements, Bug
Fixes, Balance Changes, Technical Debt / Refactoring (internal changelog only),
Known Issues and Miscellaneous. The internal changelog ends with a Metrics
section that counts commits without a task reference. With no tags it bounds the
range to `git log --oneline -n 100` rather than reading the full log. No director
gates are used. The skill asks "May I write this changelog to
`docs/CHANGELOG.md`?" with append / overwrite / decline options. Verdicts:
CHANGELOG WRITTEN after a write, COMPLETE when the user declines the write,
BLOCKED when there is no history or none of it is the game's.

---

## 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: CHANGELOG WRITTEN, COMPLETE, BLOCKED
- [ ] Contains "May I write" language (skill writes changelog)
- [ ] Has a next-step handoff (`/patch-notes` for a player-facing release, `/release-checklist`)

---

## Director Gate Checks

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

---

## Test Cases

### Case 1: Happy Path — Multiple sprints since last release tag

**Fixture:**
- Git history has a tag `v0.3.0`; it is the newest tag in the injected tag list
- Since that tag: 12 commits across sprints 006, 007, 008 — all Game commits
  (mechanics, content, bug fixes) naming systems that appear in `design/`
- `production/sprints/sprint-006.md` through `sprint-008.md` exist and list the
  stories whose task IDs appear in the commit messages
- `docs/CHANGELOG.md` does not yet exist

**Input:** `/changelog`

**Expected behavior:**
1. Skill classifies the injected commits as Game or Framework / maintenance and
   states how many of how many it used
2. Skill reads `git log --oneline v0.3.0..HEAD`
3. Skill reads the sprint plans for sprints 006–008 in `production/sprints/`
   for the context behind the changes
4. Skill categorizes changes into New Features, Improvements, Bug Fixes,
   Balance Changes, Technical Debt / Refactoring, Known Issues and
   Miscellaneous, with a Metrics section
5. Skill outputs both the internal and the player-facing changelog
6. Skill asks "May I write this changelog to `docs/CHANGELOG.md`?" with options
   [A] append, [B] overwrite, [C] no
7. User selects [B]; the file is created; verdict CHANGELOG WRITTEN

**Assertions:**
- [ ] Changelog covers the commits in `v0.3.0..HEAD`, and the output states how many of how many injected commits it used
- [ ] Entries use the skill's section set — New Features, Improvements, Bug Fixes, Balance Changes, Technical Debt / Refactoring, Known Issues, Miscellaneous — not a generic Features/Fixes split
- [ ] Sprint plans in `production/sprints/` for the covered sprints are read for context before categorizing
- [ ] Both changelogs are presented before the "May I write" prompt, and nothing is written before approval
- [ ] Verdict is CHANGELOG WRITTEN after the write

---

### Case 2: No Git Tags Found — Bounded range used

**Fixture:**
- Git repository has 20 commits and no tags; all 20 are Game commits
- The injected tag list is empty
- `docs/CHANGELOG.md` does not exist

**Input:** `/changelog`

**Expected behavior:**
1. Skill finds no tag to anchor the range
2. Skill bounds the range with `git log --oneline -n 100` — it does not read an
   unbounded full log
3. All 20 commits fall inside the 100-commit bound, so the window reaches the
   start of history and the skill does not need to ask for a start ref
4. Skill states how many of the commits it used
5. Skill compiles the categorized changelog and asks "May I write" before writing

**Assertions:**
- [ ] Skill does not error when no git tags exist
- [ ] The range is read with the bounded `git log --oneline -n 100`, never an unbounded full log
- [ ] All 20 commits are covered, and the skill does not ask for a start ref (the bound reaches the first commit)
- [ ] Output states how many of the 20 commits were used
- [ ] Changelog is still organized into sections despite the missing tag

---

### Case 3: Commit Messages Without Task IDs — Categorized by content, counted in Metrics

**Fixture:**
- Git log since the last tag has 8 Game commits
- 3 commits reference task IDs (e.g. `[STORY-012]`) matching sprint stories
- 5 commits have no task ID: "tweak dash cooldown 0.8 -> 0.6",
  "fix player clipping through ledge", "add footstep sounds", "level tweaks",
  "combat cleanup"

**Input:** `/changelog`

**Expected behavior:**
1. Skill categorizes every commit by what it changed, whether or not it has a
   task ID
2. "tweak dash cooldown 0.8 -> 0.6" goes to Balance Changes; "fix player
   clipping through ledge" goes to Bug Fixes
3. "combat cleanup" says it cleans up and names no fix, feature or tuning, so it
   goes to Technical Debt / Refactoring — in the internal changelog only
4. "level tweaks" is too vague to classify confidently and goes to
   Miscellaneous
5. The Metrics section reports `Commits without task reference: 5`
6. Skill asks "May I write" and writes on approval

**Assertions:**
- [ ] Commits are categorized by content with or without a task ID — the untagged "tweak dash cooldown 0.8 -> 0.6" lands in Balance Changes, not in a separate no-ID group
- [ ] "combat cleanup" is listed under Technical Debt / Refactoring in the internal changelog and does not appear in the player-facing changelog
- [ ] "level tweaks", too vague to classify, is listed under Miscellaneous
- [ ] Metrics section contains `Commits without task reference: 5`
- [ ] No commits are silently dropped — all 8 appear in a section

---

### Case 4: Existing CHANGELOG.md — New entry at the top, old entries preserved

**Fixture:**
- `docs/CHANGELOG.md` already exists with sections for `v0.2.0` and `v0.3.0`
- New Game commits exist since the `v0.3.0` tag

**Input:** `/changelog`

**Expected behavior:**
1. Skill compiles new entries for the period since `v0.3.0`
2. Before asking, skill checks whether `docs/CHANGELOG.md` exists — it does, so
   it recommends [A] append
3. Skill asks "May I write this changelog to `docs/CHANGELOG.md`?" with
   [A] append (recommended), [B] overwrite, [C] no
4. User selects [A]; the new entry is placed at the top of the file (newest
   first); the `v0.2.0` and `v0.3.0` sections are intact; verdict CHANGELOG WRITTEN

**Assertions:**
- [ ] Skill checks whether `docs/CHANGELOG.md` exists before asking, and recommends [A] append because it does
- [ ] The prompt offers append, overwrite and decline as distinct options
- [ ] On [A], the new entry is placed at the top of the file (newest first), not at the bottom and not replacing the file
- [ ] Existing `v0.2.0` and `v0.3.0` entries are preserved in the written file

---

### Case 5: Gate Compliance — No gate; declined write ends COMPLETE

**Fixture:**
- Git history has Game commits since the last tag
- `project.yaml` sets `modes.review_mode: full`

**Input:** `/changelog`

**Expected behavior:**
1. Skill compiles both changelogs; no director gate is spawned (the skill
   resolves only `automation`, never `review_mode`)
2. Skill goes straight from presenting the changelogs to the write prompt
3. User selects [C] No — I'll copy it manually
4. Skill stops without writing; verdict COMPLETE

**Assertions:**
- [ ] No director gate is invoked regardless of review mode
- [ ] Output does not reference any gate result
- [ ] Skill proceeds directly from presenting the changelogs to the "May I write" prompt
- [ ] On [C], no file is written and the verdict is COMPLETE, not CHANGELOG WRITTEN

---

### Case 6: Provenance Stop — Zero Game commits

**Fixture:**
- The 30 injected commits all touch 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
- `docs/CHANGELOG.md` does not exist

**Input:** `/changelog`

**Expected behavior:**
1. Skill classifies every injected commit: 0 Game, 30 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 changelog is generated and nothing is written; verdict BLOCKED

**Assertions:**
- [ ] Output names the classification result — 0 of 30 commits are Game commits
- [ ] Output contains the "does not appear to belong to" stop, not a changelog built from framework commits (no "Fixed an issue where …" copy from a hook fix)
- [ ] No "May I write" prompt appears and no file is written
- [ ] Verdict is BLOCKED — not COMPLETE and not CHANGELOG WRITTEN

---

### Case 7: No History — Not a git repository

**Fixture:**
- The project directory is not a git repository, so both injected history
  blocks are empty
- `docs/CHANGELOG.md` does not exist

**Input:** `/changelog`

**Expected behavior:**
1. The injected commit list is empty, so the provenance check is skipped —
   there is nothing to classify
2. Phase 1's `git rev-parse --is-inside-work-tree` fails; skill outputs "No git
   history found. A changelog is built from commits …"
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 says no git history was found and offers committing the work or supplying the change list directly
- [ ] No changelog is generated, no "May I write" prompt appears, and no file is written
- [ ] Verdict is BLOCKED

---

## Protocol Compliance

- [ ] Classifies the injected commits as Game or Framework / maintenance and uses only Game commits
- [ ] Reads the git log and the sprint plans in `production/sprints/` before compiling
- [ ] Always asks "May I write" before writing the changelog
- [ ] No director gates are invoked
- [ ] Verdict is CHANGELOG WRITTEN after a write, COMPLETE when the write is declined, and BLOCKED when there is no history or no Game commit
- [ ] Declares `model: sonnet` — it writes player-facing copy

---

## Coverage Notes

- A git repository with no commits yet (the same Phase 1 stop as Case 7) is not
  separately tested.
- More than 100 commits with no tag (the skill says so and asks for a start ref
  instead of widening the range) is not tested.
- Merge commits vs. squash commits are not explicitly differentiated in
  these tests; implementation detail of the git log parsing phase.
- The `/patch-notes` skill should be run after `/changelog` for player-facing
  output; that handoff is verified in the patch-notes spec.