pixelheros/CCGS Skill Testing Framework/skills/sprint/changelog.md

# Skill Test Spec: /changelog

## Skill Summary

`/changelog` is a Haiku-tier skill that auto-generates a developer-facing
changelog by reading git commit history and closed sprint stories since the
last release tag. It organizes entries into features, fixes, and known issues.
No director gates are used. The skill asks "May I write to `docs/CHANGELOG.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 changelog)
- [ ] Has a next-step handoff (e.g., run /patch-notes for player-facing version)

---

## 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` three sprints ago
- Since that tag: 12 commits across sprints 006, 007, 008
- Sprint story files reference task IDs matching commit messages
- `docs/CHANGELOG.md` does not yet exist

**Input:** `/changelog`

**Expected behavior:**
1. Skill reads git log since `v0.3.0` tag
2. Skill reads sprint stories to cross-reference task IDs
3. Skill compiles entries into Features, Fixes, and Known Issues sections
4. Skill presents draft to user
5. Skill asks "May I write to `docs/CHANGELOG.md`?"
6. User approves; file written; verdict COMPLETE

**Assertions:**
- [ ] Changelog covers commits since the most recent git tag
- [ ] Entries are organized into Features / Fixes / Known Issues sections
- [ ] Sprint story references are used to enrich commit descriptions
- [ ] "May I write" prompt appears before file write
- [ ] Verdict is COMPLETE after write

---

### Case 2: No Git Tags Found — All commits used, version baseline noted

**Fixture:**
- Git repository has commits but no tags exist
- 20 commits in history across 3 sprints

**Input:** `/changelog`

**Expected behavior:**
1. Skill checks for git tags — finds none
2. Skill uses all commits in history as the baseline
3. Skill notes in the output: "No version tag found — using full commit history; version baseline is unset"
4. Skill still compiles organized changelog from available commits
5. Skill asks "May I write" and writes on approval

**Assertions:**
- [ ] Skill does not error when no git tags exist
- [ ] Output explicitly notes that no version baseline was found
- [ ] Full commit history is used as the source
- [ ] Changelog is still organized into sections despite missing tag

---

### Case 3: Commit Messages Without Task IDs — Grouped by date with note

**Fixture:**
- Git log since last tag has 8 commits
- 5 commits have no task ID in the message (e.g., "fix typo", "tweak values")
- 3 commits reference task IDs matching sprint stories

**Input:** `/changelog`

**Expected behavior:**
1. Skill reads commits and sprint stories
2. 3 commits are matched to sprint stories and placed in appropriate sections
3. 5 untagged commits are grouped by date under a "Misc" or "Other Changes" section
4. Output notes: "5 commits without task IDs — grouped by date"
5. Skill writes changelog on approval

**Assertions:**
- [ ] Commits with task IDs are placed in appropriate sections (Features or Fixes)
- [ ] Commits without task IDs are grouped separately with a note
- [ ] Output flags the number of commits missing task references
- [ ] No commits are silently dropped from the changelog

---

### Case 4: Existing CHANGELOG.md — New section prepended, old entries preserved

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

**Input:** `/changelog`

**Expected behavior:**
1. Skill detects that `docs/CHANGELOG.md` already exists
2. Skill compiles new entries for the period since `v0.3.0`
3. Skill presents draft with new section prepended above existing content
4. Skill asks "May I write to `docs/CHANGELOG.md`?" (confirming prepend strategy)
5. User approves; new content is prepended, old entries intact; verdict COMPLETE

**Assertions:**
- [ ] Skill reads existing changelog before writing to detect prior content
- [ ] New section is prepended (not appended or overwriting) existing entries
- [ ] Old changelog entries for v0.2.0 and v0.3.0 are preserved in the written file
- [ ] "May I write" prompt reflects the prepend operation

---

### Case 5: Gate Compliance — No gate; read-then-write with approval

**Fixture:**
- Git history has commits since last tag
- `review-mode.txt` contains `full`

**Input:** `/changelog`

**Expected behavior:**
1. Skill compiles changelog in full mode
2. No director gate is invoked (changelog generation is compilation, not a delivery gate)
3. Skill runs on Haiku model — fast compilation
4. Skill asks user for approval and writes file on confirmation

**Assertions:**
- [ ] No director gate is invoked regardless of review mode
- [ ] Output does not reference any gate result
- [ ] Skill proceeds directly from compilation to "May I write" prompt
- [ ] Verdict is COMPLETE

---

## Protocol Compliance

- [ ] Reads git log and sprint story files before compiling
- [ ] Always asks "May I write" before writing changelog
- [ ] No director gates are invoked
- [ ] Verdict is always COMPLETE
- [ ] Runs on Haiku model tier (fast, low-cost)

---

## Coverage Notes

- The case where git is not initialized in the repository is not tested;
  behavior would depend on git command failure handling.
- 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.