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

Skill Test Spec: /hotfix

Skill Summary

/hotfix runs an emergency fix outside the sprint process, with an audit trail. It runs only when the user types it (disable-model-invocation: true). The flow:

1. Assess severity (S1 Critical / S2 High / S3 or lower, on /bug-triage's scale) and confirm it with AskUserQuestion; S3 or lower stops with Verdict: **REDIRECTED**.
2. Hotfix record — asks "May I write this to production/hotfixes/hotfix-[date]-[short-name].md?"
3. Branch — checks for a git repo, then asks before running git checkout -b hotfix/[short-name] [base-ref]. [base-ref] is the release the bug is in: its tag on main, or its release/* branch if one was cut to stabilise it — never the head of main.
4. Investigate and propose — root cause and minimal fix, then "May I implement this fix?" before any code changes; implement, run targeted tests.
5. Approvals — lead-programmer, qa-tester and producer spawned in parallel; all three must return APPROVE, and CONCERNS or REJECT blocks deployment.
6. QA re-entry gate — qa-lead picks smoke check, targeted /team-qa feature: [system], or full QA; a smoke-check FAIL sends the fix back to Phase 4. A NOT ASSESSED result is not a pass: deploying anyway takes an explicit producer decision, logged in the hotfix record.
7. Deploy — an unconditional AskUserQuestion before any merge, tag or deploy (even in autonomous mode); merge to main, and to the release's release/* branch only if one exists; tag the patch release and verify the backport; ask before updating the bug file, then set it to Fixed — Pending Verification; print "Hotfix Deployed" (on [B], "Hotfix Merged to main — release held", with no Tag); [C] stops with no merge, tag or bug-file update; then /bug-report verify (a CANNOT VERIFY is settled by playing the reproduction steps and answering its manual-play question) and a post-incident review (recorded with the incident-response template — /retrospective has no incident mode).

Targeted tests run with commands.test from project.yaml; when it is unset or no test covers the system, the hotfix record says Tests: NOT RUN — [reason]. A /team-qa pass that returns NOT APPROVED or BLOCKED is handled like a smoke-check FAIL. S1 is /bug-triage's definition: crash, data loss, or complete feature failure.

---

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
• Frontmatter sets disable-model-invocation: true
• Has ≥2 phase headings
• Contains verdict keywords: REDIRECTED, APPROVE / CONCERNS / REJECT (sign-offs), NOT ASSESSED (QA gate)
• Contains "May I write" (hotfix record), "May I implement this fix?" (code) and "May I update" (bug file) language
• Has a next-step handoff (/bug-report verify [BUG-ID], a post-incident review)

---

Director Gate Checks

No named director-gate ID (CD-, TD-, AD-, PR-) is used and the review mode does not apply. Phase 5 spawns three blocking sign-offs in parallel — lead-programmer, qa-tester and producer (the only director-tier agent) — and all three must return APPROVE before deployment. Phase 5b spawns qa-lead to choose the QA scope.

---

Test Cases

Case 1: Happy Path — S1 crash fixed with record, branch, approvals and backport

Fixture:

• Git repository; the live build is the release tag v1.2.0 on main, and no release/* branch exists (the trunk default)
• Bug in src/gameplay/arena.gd (crash on boss arena entry); production/qa/bugs/BUG-0031.md exists with **Status**: Open
• All three sign-offs return APPROVE; qa-lead picks a smoke check, which returns PASS

Input: /hotfix BUG-0031

Expected behavior:

1. Assesses S1 and confirms via AskUserQuestion; user picks [A] S1 (Critical)
2. Asks "May I write this to production/hotfixes/hotfix-[date]-boss-arena-crash.md?" and writes it
3. Runs git rev-parse --is-inside-work-tree, asks "Ready to create hotfix branch 'hotfix/boss-arena-crash' from v1.2.0?", and runs git checkout -b hotfix/boss-arena-crash v1.2.0 only after [A] Yes — create branch
4. Presents root cause and minimal fix, asks "May I implement this fix?", then implements and runs targeted tests
5. Spawns lead-programmer, qa-tester and producer in parallel; all APPROVE
6. qa-lead → smoke check PASS
7. Asks "Hotfix validated and approved. Merge to main, tag v1.2.1 and deploy?" (no release branch is named — none exists); user picks [A]
8. Merges to main, tags v1.2.1 on the fixed build, and confirms the fix is on main
9. Asks "May I update production/qa/bugs/BUG-0031.md …?" before setting it to Fixed — Pending Verification, then prints "Hotfix Deployed: boss-arena-crash" with Tag: v1.2.1 and Next: /bug-report verify

Assertions:

• The hotfix record is written before the branch is created
• The branch starts from the release tag v1.2.0, not from the head of main
• The branch is created only after the user picks [A]
• No code is modified before "May I implement this fix?" is approved
• The three sign-off agents are spawned as simultaneous Agent calls
• No merge happens before the Phase 6 deploy question is answered
• No release/* branch is created or merged; the patch release is tagged
• The summary's Backport line states presence on main
• The bug file is not edited before the user approves the "May I update" question
• BUG-0031.md Status becomes Fixed — Pending Verification

---

Case 2: Sign-off REJECT — Deployment blocked

Fixture:

• Fix implemented for an S1 bug
• qa-tester returns REJECT: "Player health clamping regression detected"; lead-programmer and producer return APPROVE

Input: /hotfix

Expected behavior:

1. Phase 5 collects all three responses
2. Because one returned REJECT, the skill does not deploy: it surfaces the regression and resolves it first
3. The Phase 5b QA gate and the Phase 6 deploy question are not reached while the REJECT stands
4. No merge, tag or deploy occurs

Assertions:

• The qa-tester's REJECT and its regression are shown to the user
• Skill does not proceed to deployment with a REJECT outstanding
• The deploy AskUserQuestion is not issued while the REJECT stands
• No merge is performed

---

Case 3: Release Branch — Deploy approval holds even in autonomous mode

Fixture:

• project.yaml sets modes.automation: autonomous
• The live release v1.3.0 has a release/1.3 branch, cut to stabilise it for certification; the hotfix branch was started from release/1.3
• An S2 fix has all three APPROVE sign-offs and a smoke check PASS

Input: /hotfix

Expected behavior:

1. Despite autonomous, Phase 6 asks "Hotfix validated and approved. Merge to main and release/1.3, tag v1.3.1 and deploy?" with [A] Yes — merge and deploy / [B] Merge to main only — hold the release / [C] Stop here
2. User picks [B]
3. The fix is merged to main only; nothing is merged to release/1.3, tagged or deployed
4. The summary is titled "Hotfix Merged to main — release held" and has no Tag line

Assertions:

• The deploy question is asked even though modes.automation is autonomous
• The question names release/1.3, because this release has one
• All three options are offered
• With [B], release/1.3 is not merged, no tag is created and nothing is deployed
• With [B], main receives the fix
• With [B], the summary does not say "Deployed" and names no tag

---

Case 4: Not an Emergency — a cosmetic S4 redirected before any work

Fixture:

• User reports a typo on the credits screen

Input: /hotfix typo in the credits screen

Expected behavior:

1. Phase 1 assesses S4 (Low — cosmetic) and asks the user to confirm severity
2. User picks [C] S3 or lower — redirect to normal bug fix workflow
3. Skill stops: Verdict REDIRECTED — use the normal bug fix workflow for S3 and below

Assertions:

• Severity is confirmed via AskUserQuestion with S1 / S2 / S3-or-lower options
• Verdict is REDIRECTED
• No hotfix record is written and no branch is created
• No code is modified and no agents are spawned

---

Case 5: Director Gate Check — Producer sign-off, and NOT ASSESSED QA is not a pass

Fixture:

• project.yaml: modes.rigor: standard (so a project with no game tests gets NOT ASSESSED, not WAIVED)
• S1 fix implemented; all three sign-offs APPROVE
• qa-lead picks a smoke check; /smoke-check returns NOT ASSESSED — no game tests found

Input: /hotfix

Expected behavior:

1. producer is spawned as a blocking sign-off, not as a named director gate; no gate IDs appear
2. The NOT ASSESSED QA result is treated as unmet, not as a pass
3. The skill either obtains the missing result or takes the decision to the producer explicitly as a decision to deploy an unverified hotfix. This escape hatch is deliberate: an emergency fix may have to ship before a suite exists, but only as a named decision, never as a gate that quietly cleared
4. If the producer decides to deploy unverified, that decision — who made it and why — is logged in the hotfix record, and the summary's QA gate line reads NOT ASSESSED with why and whose explicit decision it was

Assertions:

• No gate IDs (CD-, TD-, AD-, PR-) appear in output
• NOT ASSESSED does not advance to Phase 6 as if the QA gate passed
• Deployment goes ahead only with the three APPROVE sign-offs plus an explicit producer decision to deploy unverified
• That decision is logged in the hotfix record
• The summary records the QA gate as NOT ASSESSED with the reason and whose decision it was

---

Case 6: Smoke Check FAIL — back to Phase 4, and a CONCERNS sign-off still blocks

Fixture:

• S1 fix implemented; all three sign-offs APPROVE; qa-lead picks a smoke check
• /smoke-check returns FAIL: "Player health clamping regression detected"
• On the revised fix, lead-programmer returns CONCERNS ("the clamp now runs on the save path too"); qa-tester and producer return APPROVE

Input: /hotfix

Expected behavior:

1. The FAIL stops deployment: the skill returns to Phase 4 with the failing check, presents a revised fix and asks "May I implement this fix?" again before changing code
2. After implementing it (Phase 4b), it re-runs all three Phase 5 sign-offs — qa-tester's regression run among them — and then the QA step
3. lead-programmer's CONCERNS blocks exactly as a REJECT does: it is shown to the user and resolved before the skill continues
4. The Phase 6 deploy question is asked only once all three return APPROVE and a re-run smoke check passes

Assertions:

• A smoke-check FAIL never reaches the deploy question
• The revised fix gets its own "May I implement this fix?" approval
• All three sign-offs and the QA step are re-run for the revised fix
• CONCERNS from a sign-off blocks deployment until resolved; it is not treated as an approval
• No merge, tag or deploy occurs while the FAIL or the CONCERNS stands

---

Protocol Compliance

• Confirms severity before any work; S3 or lower is REDIRECTED
• Asks "May I write" before the hotfix record
• Asks before creating the branch
• Asks "May I implement this fix?" before modifying code
• Runs targeted tests with commands.test, never a runner line from memory; with the key unset (or no covering test) records Tests: NOT RUN — [reason]
• Treats a /team-qa NOT APPROVED or BLOCKED like a smoke-check FAIL
• On the deploy question's [C] Stop here, merges, tags and updates nothing, and the record stays IN PROGRESS
• Deploys only with all three APPROVE sign-offs and a QA gate that ran — or, when the QA gate was NOT ASSESSED, an explicit producer decision to deploy unverified, logged in the hotfix record
• Asks before any merge, tag or deploy regardless of modes.automation
• Starts the hotfix branch from the release it fixes (its tag, or its release/* branch if one exists)
• Verifies the backport on main, and on the release's release/* branch only when one exists
• Asks "May I update" before editing the bug file

---

Coverage Notes

• A non-git working directory ("Not a git repository — create the branch manually.") is not separately tested.
• qa-lead choosing a targeted /team-qa feature: [system] pass (APPROVED / APPROVED WITH CONDITIONS) or full QA is not separately tested.
• Phase 7 post-deploy verification (VERIFIED FIXED → /bug-report close; STILL PRESENT → re-open and assess rollback; CANNOT VERIFY → the bug stays open until its reproduction steps are played in the deployed build and reported through /bug-report verify's manual-play question) is not separately tested.