Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/utility/skill-improve.md

# Skill Test Spec: /skill-improve

## Skill Summary

`/skill-improve [skill-name]` runs one test → fix → retest → keep-or-revert
cycle on a single skill. It records a static baseline with
`/skill-test static [name]` (FAIL and WARN counts, and which of Checks 1–7
failed), then a category baseline with `/skill-test category [name]` when the
skill has a `category:` in `CCGS Skill Testing Framework/catalog.yaml`. If both
baselines are clean it stops with "No improvements needed." Otherwise it shows
a diagnosis, proposes before/after fixes, asks "May I write this improved
version to `.claude/skills/[name]/SKILL.md`?", writes, re-runs the same tests,
and shows a before → after comparison per dimension plus one combined line
(`Combined: 3 → 0 (improved)`).

Phase 6 compares the combined count (static FAILs + category FAILs + static
WARNs + category WARNs). Lower than baseline → "Score improved. Changes kept."
Same or worse → "Combined score did not improve." followed by "May I restore
`.claude/skills/[name]/SKILL.md` to the content it had before this run?" — the
restore runs only on a yes, and writes back the copy recorded in Phase 5 (never
`git checkout`, which would also drop earlier uncommitted edits). No director gates apply.

---

## 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
- [ ] Phase 6 states both outcomes: "Score improved. Changes kept." and "Combined score did not improve."
- [ ] Contains "May I write" collaborative protocol language before applying fixes
- [ ] Has a next-step handoff (Phase 7: `/skill-test static all`, `/skill-improve [next-name]`, `/skill-test audit`)

---

## Director Gate Checks

None. `/skill-improve` is a meta-utility skill. No director gates apply.

---

## Test Cases

### Case 1: Happy Path — Check 4 FAIL and Check 5 WARN fixed, changes kept

**Fixture:**
- `.claude/skills/some-skill/SKILL.md` has `Write` in `allowed-tools` but no
  ask-before-write language (Check 4 FAIL) and no next-step section (Check 5 WARN)
- catalog gives `some-skill` `category: utility`; its category baseline is
  1 FAIL (U1, because static checks fail)
- The user approves the write; the re-test is clean in both dimensions

**Input:** `/skill-improve some-skill`

**Expected behavior:**
1. Static baseline displayed: "Static baseline: 1 failures, 1 warnings" with
   "Failing: Check 4 (no ask-before-write), Check 5 (no handoff)"
2. Category baseline displayed: "Category baseline: 1 failures, 0 warnings (utility rubric)"
3. Full diagnosis shown before any change is proposed
4. Before/after blocks proposed for only the failing parts; skill asks
   "May I write this improved version to `.claude/skills/some-skill/SKILL.md`?"
5. File written; both tests re-run; comparison shows
   `Static: Before 1 failures, 1 warnings → After 0 failures, 0 warnings`, the
   category line, and one combined line, `Combined: 3 → 0 (improved)`
6. "Score improved. Changes kept." with a per-dimension summary

**Assertions:**
- [ ] Static and category baselines are displayed before any change is proposed
- [ ] Both Check 4 and Check 5 are diagnosed and addressed in the proposed fix
- [ ] "May I write" is asked before the file is written
- [ ] The before → after comparison is shown for both dimensions, plus the single line `Combined: 3 → 0 (improved)`
- [ ] Outcome is "Score improved. Changes kept."

---

### Case 2: Fix Causes Regression — revert offered, runs only on yes

**Fixture:**
- `.claude/skills/some-skill/SKILL.md` has a static baseline of 0 FAILs and
  1 WARN (Check 5, no handoff)
- The applied fix adds a handoff but deletes the section holding the verdict
  keywords and the ask-before-write line: the static re-test shows 2 FAILs
  (Checks 3 and 4), and the category result is no better than its baseline —
  the combined count rises
- The user approves the write, then answers yes to the revert

**Input:** `/skill-improve some-skill`

**Expected behavior:**
1. Baseline recorded; fix proposed; "May I write …" approved; file written
2. The re-test comparison's combined line reads `Combined: [before] → [after] (worse)`,
   with the after count higher
3. Skill reports "Combined score did not improve." and shows what changed and
   why it may not have helped
4. Skill asks "May I restore `.claude/skills/some-skill/SKILL.md` to the content it had before this run?"
5. On yes: writes the Phase 5 copy back with Write — it does not run `git checkout`

**Assertions:**
- [ ] Re-test combined count is compared to the baseline before finalizing
- [ ] A higher combined count takes the "did not improve" branch
- [ ] The revert is asked for, not automatic
- [ ] The file is restored only after the user says yes, from the recorded copy — never via `git checkout`
- [ ] "Score improved. Changes kept." is NOT reported

---

### Case 3: Gate Skill — combined static + category baseline

**Fixture:**
- `.claude/skills/gate-check/SKILL.md` has 1 static FAIL and 2 category FAILs
  (G2 and G4 of the `### gate` section in `CCGS Skill Testing Framework/quality-rubric.md`)
- catalog gives `gate-check` `category: gate`; the user approves the write, and
  the re-test is clean in both dimensions

**Input:** `/skill-improve gate-check`

**Expected behavior:**
1. Static baseline and category baseline (`gate rubric`) both recorded
2. Diagnosis names the static check and the two G-metrics with the exact text gap for each
3. "May I write this improved version to `.claude/skills/gate-check/SKILL.md`?"
4. Both `/skill-test static gate-check` and `/skill-test category gate-check` re-run
5. The comparison ends `Combined: 3 → 0 (improved)`: "Score improved. Changes kept."

**Assertions:**
- [ ] Both static and category scores are captured in the baseline
- [ ] The combined count (FAILs + WARNs, both dimensions) is what Phase 6 compares
- [ ] All 3 failures are addressed in the proposed fix
- [ ] Both test types are re-run after the write
- [ ] Outcome is "Score improved. Changes kept." with the combined before/after

---

### Case 4: Skill Already Clean — No improvements needed

**Fixture:**
- `.claude/skills/brainstorm/SKILL.md` has 0 static FAILs and 0 WARNs
- catalog gives `brainstorm` `category: utility`; U1 and U2 both pass

**Input:** `/skill-improve brainstorm`

**Expected behavior:**
1. Static baseline 0/0 → proceeds to the category baseline (not an immediate stop)
2. Category baseline 0/0 (utility rubric)
3. Skill stops: "This skill already passes all static and category checks. No improvements needed."
4. No diagnosis, no proposed change, no "May I write", no file modified

**Assertions:**
- [ ] The category baseline is run before stopping (a clean static result alone does not stop)
- [ ] "No improvements needed" message is shown
- [ ] No changes are proposed
- [ ] No "May I write" is asked and no file is modified

---

### Case 5: Director Gate Check — No gate; skill-improve is a meta utility

**Fixture:**
- `.claude/skills/some-skill/SKILL.md` has at least 1 static failure; the user
  approves the write

**Input:** `/skill-improve some-skill`

**Expected behavior:**
1. Skill runs the test-fix-retest loop
2. No director agents are spawned
3. No gate IDs appear in output

**Assertions:**
- [ ] No director gate is invoked
- [ ] No gate skip messages appear
- [ ] The run ends with one of Phase 6's two outcome messages — no gate verdict

---

### Case 6: Equal Score — "no change" does not keep the fix as an improvement

**Fixture:**
- `.claude/skills/some-skill/SKILL.md` has a static baseline of 0 FAILs and
  1 WARN (Check 7, argument hint does not match the documented modes)
- catalog gives `some-skill` no `category:`, so category checks are skipped
- The applied fix corrects the hint but drops the closing next-step section:
  the re-test shows 0 FAILs and 1 WARN (Check 5)
- The user approves the write, then answers no to the restore

**Input:** `/skill-improve some-skill`

**Expected behavior:**
1. "Category: not yet assigned — skipping category checks." is shown
2. The comparison's combined line reads `Combined: 1 → 1 (no change)`
3. An equal count takes the "did not improve" branch: "Combined score did not
   improve.", then "May I restore `.claude/skills/some-skill/SKILL.md` to the
   content it had before this run?"
4. On no, the file is left as written and nothing is restored

**Assertions:**
- [ ] An equal combined count is treated as "did not improve", not as improved
- [ ] The combined line reads `Combined: 1 → 1 (no change)`
- [ ] "Score improved. Changes kept." is NOT reported
- [ ] The restore is asked for, and declining it leaves the written file in place

---

## Protocol Compliance

- [ ] Always establishes a baseline before proposing any changes
- [ ] Shows the full diagnosis, then before/after blocks, before asking to write
- [ ] Asks "May I write" before applying any fix
- [ ] Detects a non-improvement by comparing the re-test combined count to the baseline — an equal count is a non-improvement
- [ ] Shows one combined before → after line, e.g. `Combined: 3 → 0 (improved)`, beside the per-dimension lines
- [ ] Asks for user confirmation before reverting (not automatic)
- [ ] Ends with "Score improved. Changes kept." or "Combined score did not improve." — or stops earlier with "No improvements needed." / a declined write

---

## Coverage Notes

- One fix-retest cycle per invocation; a further pass needs a new `/skill-improve` run.
- Behavioral (spec-mode) results are not part of the loop — only static and
  category scores are.
- The Phase 1 stops — usage text when no argument is given, "Skill '[name]' not
  found." when no `SKILL.md` exists — and the user declining the write in
  Phase 4 are not separately fixture-tested.