Regression Suite Maintenance

!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.

Regression Suite

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:

• After fixing a bug (confirm a regression test was written or identify gap)
• Before a phase gate — at qa.level: full, /gate-check requires a regression suite
• As part of sprint close to detect coverage drift

Every 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.

1. Parse Arguments

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 reviews
• No argument — if a sprint is clearly active (sprint plan exists with in-progress stories), run update. If ambiguous or no active sprint is detected, use AskUserQuestion:
  • Prompt: "No subcommand specified. Which mode do you want to run?"
  • Options:
    • [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)

2. Load Context

Step 2a — Load existing regression suite

Read tests/regression-suite.md if it exists. Extract:

• Total registered regression tests
• Last updated date
• Any tests flagged as STALE or QUARANTINED

If it does not exist: note "No regression suite found — will create one."

Step 2b — Load test inventory

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.

Step 2c — Load GDD critical paths

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.)

For each in-scope MVP-tier system's GDD, extract:

• Acceptance Criteria (these define the critical paths)
• Formulas section (formulas must have regression tests)
• Edge Cases section (known edge cases should have regression tests)

For update mode: skip full GDD scan. Instead read the current sprint plan and story files to find stories with Status: Complete this sprint.

Step 2d — Load closed bugs

Glob production/qa/bugs/*.md and filter for bugs with a Status: Closed or Status: Fixed field. Note:

• Which story or system the bug was in
• Whether a regression test was mentioned in the fix description

3. Map Coverage — Critical Paths

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:

1. Grep tests/unit/[system]/ and tests/integration/[system]/ for file names and function names related to the criterion's key noun/verb
2. Assign coverage:

3. Elevate MISSING items that correspond to formulas or state machines to HIGH PRIORITY gap — these are the most likely regression sources.

4. Map Coverage — Fixed Bugs

For each closed bug:

1. Extract the system slug from the bug's metadata
2. Grep tests/unit/[system]/ and tests/integration/[system]/ for a test that references the bug ID or the specific failure scenario
3. Assign:
   • HAS REGRESSION TEST — a test was found that would catch this bug
   • MISSING REGRESSION TEST — bug was fixed but no test guards against recurrence

For MISSING REGRESSION TEST items:

• Flag them as regression gaps
• Suggest the test file path: tests/unit/[system]/[bug-slug]_regression_test.[ext]
• Note: "Without this test, this bug can silently return in a future sprint."