Map test coverage to GDD critical paths, find fixed bugs lacking regression tests, flag drift from new features.
74%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Fix and improve this skill with Tessl
tessl review fix ./.claude/skills/regression-suite/SKILL.md!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation,workflow,qa.level,system_overrides
Resolved above — use as-is. No block → defaults in
.claude/docs/config-resolution.md.
This skill ensures that every bug fix is backed by a test that would have caught the original bug — and that the regression suite stays current as the game evolves. It also detects when new features have been added without corresponding regression coverage.
A regression suite is not a new test category — it is a curated list of
tests already in tests/ that collectively cover the game's critical paths
and known failure points. This skill maintains that list.
Output: tests/regression-suite.md
When to run:
qa.level: full, /gate-check requires a regression suiteEvery AskUserQuestion call follows .claude/docs/automation-modes.md
(collaborative asks always · guided major-only · autonomous logs and proceeds;
automation_always_ask categories always prompt).
Workflow tier: modes.workflow as resolved above — supplied by modes.rigor
unless set explicitly — per .claude/docs/workflow-modes.md; in audit mode consider
workflow_overrides.system_overrides.<system> per system as each GDD is read. It
sets whether GDD critical paths are mapped or coverage is smoke-only — see Step 2c.
qa.level: controls whether the suite is generated at
all. At minimal, the regression suite is not generated (report that and
stop); at standard, generate it at Polish-stage entry; at full, at
Production-stage entry. Distinct axis from workflow.
Early qa.level guard (resolved above): if qa.level: minimal, the
regression suite is not generated — report "Regression suite not generated at
qa.level minimal" and STOP here, before any scan, in every mode
(update / audit / report). This is the qa.level axis; it is distinct from
the workflow-tier minimal branch in Step 2c (which only changes the
critical-path source, not whether the suite runs). Do not enter Step 2c's
minimal branch on account of qa.level. This stop's verdict is
NOT ASSESSED (Section 7) — tests are not required at this level, and nothing
was scanned.
Modes:
/regression-suite update — scan new bug fixes this sprint and check
for regression test presence; add new tests to the suite manifest/regression-suite audit — full audit of all GDD critical paths vs.
existing test coverage; flag paths with no regression test/regression-suite report — read-only status report (no writes); suitable
for sprint reviewsupdate. If ambiguous or no active sprint is detected, use AskUserQuestion:
[A] update — scan new bug fixes this sprint and add missing regression tests[B] audit — full audit of all GDD critical paths vs. existing test coverage[C] report — read-only status report (no writes)Read tests/regression-suite.md if it exists. Extract:
STALE or QUARANTINEDIf it does not exist: note "No regression suite found — will create one."
Glob all test files:
tests/unit/**/*_test.*
tests/integration/**/*_test.*
tests/regression/**/*For each file, note the system (from directory path) and file name. Do not read test file contents unless needed for name-to-test mapping.
For audit mode: read design/gdd/systems-index.md to get all systems, then
scope the scan by each system's workflow tier (resolved above):
full — read the GDD and map critical paths from all sections.standard — same, from the required sections (Acceptance Criteria, Edge
Cases, and Formulas where the system defines numeric rules).
A system pinned higher via system_overrides is mapped at its higher tier.minimal — skip the GDD critical-path scan. Instead read the latest
smoke-check report in production/qa/smoke-*.md and take the critical paths it
exercises as the regression scope (Step 3 maps coverage against those, not GDD
acceptance criteria). If no smoke report exists, stop with Verdict: NOT
ASSESSED — no smoke report to take critical paths from — there is no
critical-path source at minimal without one; run /smoke-check first.(Tier affects audit mode only; update and report modes are tier-independent.)
Read each GDD by section: find the headings you need with the Grep tool (pattern
^#, content mode) and Read those ranges with offset and limit. At full that
is every section, read in ranges, since a whole-file Read over 40 KB is refused.
For each in-scope MVP-tier system's GDD, extract:
For update mode: skip full GDD scan. Instead read the current sprint plan
and story files to find stories with Status: Complete this sprint.
Glob production/qa/bugs/*.md and filter for bugs with a Status: Closed
or Status: Fixed field. Note:
For audit mode only. (At minimal the critical paths come from the smoke-check
report identified in Step 2c, not from GDD acceptance criteria — map coverage
against those smoke paths and skip the GDD-criterion loop below.)
For each GDD acceptance criterion, determine whether a test exists:
tests/unit/[system]/ and tests/integration/[system]/ for file names
and function names related to the criterion's key noun/verb| Status | Meaning |
|---|---|
| COVERED | A test file exists that targets this criterion's logic |
| PARTIAL | A test exists but doesn't cover all cases (e.g. happy path only) |
| MISSING | No test found for this critical path |
| EXEMPT | Visual/Feel or UI criterion — not automatable by design |
For each closed bug:
tests/unit/[system]/ and tests/integration/[system]/ for a test
that references the bug ID or the specific failure scenarioFor MISSING REGRESSION TEST items:
tests/unit/[system]/[bug-slug]_regression_test.[ext]Coverage drift occurs when the game grows but the regression suite doesn't.
Check for drift indicators:
tests/systems-index.md since the last regression-suite updatetests/regression-suite.md last-updated date vs. current date — if gap >
2 sprints, flag as likely stale## Regression Suite Status
**Mode**: [update | audit | report]
**Existing registered tests**: [N]
**Test files scanned**: [N]
### Critical Path Coverage (audit mode only)
| System | Total ACs | Covered | Partial | Missing | Exempt |
|--------|-----------|---------|---------|---------|--------|
| [name] | [N] | [N] | [N] | [N] | [N] |
**Coverage rate (non-exempt)**: [N]%
### Bug Regression Coverage
| Bug ID | System | Severity | Has Regression Test? |
|--------|--------|----------|----------------------|
| BUG-NNNN | [system] | S[N] | YES / NO ⚠ |
**Bugs without regression tests**: [N]
### Coverage Drift Indicators
[List new systems or stories with no test coverage, or "None detected."]
### Recommended New Regression Tests
| Priority | System | Suggested Test File | Covers |
|----------|--------|---------------------|--------|
| HIGH | [system] | `tests/unit/[system]/[slug]_regression_test.[ext]` | BUG-NNNN / AC-[N] |
| MEDIUM | [system] | `tests/unit/[system]/[slug]_test.[ext]` | [criterion] |tests/regression-suite.md)Before computing coverage, check the denominator. If the GDD glob returns zero critical paths, or the test globs return zero test files, do not emit a percentage — report
Coverage: NOT ASSESSED — [no GDDs found | no test files found]and name which side was empty and the skill that produces it (/map-systemsand/design-systemfor GDDs,/test-setupfor the test scaffold).A percentage computed from an empty denominator is not a low score; it is not a number.
0%reads as "measured and terrible" and100%as "measured and perfect" — both are claims about a comparison that never happened. This is the same defect/scope-checkcarries a Phase 4 guard against, in the same words: "a percentage computed from no baseline items is not a small number; it is not a number."
The manifest is a curated index — not the tests themselves, but a registry of which tests should always pass before a release:
# Regression Suite Manifest
> Last Updated: [date]
> Total registered tests: [N]
> Coverage: [N]% of GDD critical paths
## How to run
[Engine-specific command to run all regression tests]
## Registered Regression Tests
### [System Name]
| Test File | Test Function (if known) | Covers | Added |
|-----------|--------------------------|--------|-------|
| `tests/unit/[system]/[file]_test.[ext]` | `test_[scenario]` | AC-N / BUG-NNNN | [date] |
## Known Gaps
Tests that should exist but don't yet:
| Priority | System | Suggested Path | Covers | Reason Not Yet Written |
|----------|--------|----------------|--------|------------------------|
| HIGH | [system] | `tests/unit/[system]/[path]` | BUG-NNNN | Bug fixed without test |
## Quarantined Tests
Tests that are flaky or disabled (do not run in CI):
| Test File | Function | Reason | Quarantined Since |
|-----------|----------|--------|-------------------|
| (none) | | | |In update or audit mode, ask: "May I write/update tests/regression-suite.md with the current
regression suite manifest?"
For update mode: append new entries; never remove existing entries
(use Edit with targeted insertions).
For audit mode: rewrite the full manifest with updated coverage data.
For report mode: do not write anything.
After writing (if approved):
/test-helpers to scaffold the test file."/regression-suite audit at the next sprint boundary."At workflow: minimal, which has no sprints, say "next story" for "next sprint" in the three lines above.
Verdict, first match wins:
qa.level: minimal: "Regression
suite not generated at qa.level minimal". Tests are not required at this
level; nothing was scanned or written.minimal stop above: no smoke report to take critical
paths from; name /smoke-check as the fix.Coverage: NOT ASSESSED — [reason] (no GDDs or
no test files); name the reason. Never report COMPLETE over a coverage figure
that was not computed.update or audit mode and the user declined the write.update / audit: regression suite updated; report: coverage
report shown (report mode writes nothing).Applies in collaborative mode (the default). For guided and
autonomous modes, see .claude/docs/automation-modes.md — the rules below
describe what collaborative mode requires, not universal behavior.
qa.level: full, where phase gates require the regression suite)/test-flakinessDonchitos/Claude-Code-Game-Studios
abc0de7
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.