/regression-suite

name: regression-suite
description: "Map test coverage to GDD critical paths, identify fixed bugs without regression tests, flag coverage drift from new features, and maintain tests/regression-suite.md. Run after implementing a bug fix or before a release gate."
argument-hint: "[update | audit | report]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion
model: sonnet

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 release gate (`/gate-check polish` requires regression suite exists)
• As part of sprint close to detect coverage drift

---

1. Parse Arguments

**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. For each MVP-tier system, read its GDD and 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:

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:

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

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

---

5. Detect Coverage Drift

Coverage drift occurs when the game grows but the regression suite doesn't.

Check for drift indicators:

• Stories completed this sprint with no corresponding test files in `tests/`
• New systems added to `systems-index.md` since the last regression-suite update
• GDD sections added or revised since the regression suite was last updated

(use Grep on GDD file modification hints if available, or ask the user)

• `tests/regression-suite.md` last-updated date vs. current date — if gap >

2 sprints, flag as likely stale

---

6. Generate Report and Suite Manifest

Report format (in conversation)

## 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-NNN | [system] | S[N]