/test-review

name: test-review
description: "Test coverage review via Codex exec. Use when: reviewing test sufficiency, identifying coverage gaps, test quality audit. Not for: generating tests (use codex-test-gen), code review (use codex-code-review). Output: coverage analysis + gap report."
allowed-tools: Bash(git:*), Bash(node:*), Read, Grep, Glob, Write, Task
context: fork
agent: Explore

Test Review Skill

Trigger

• Keywords: test coverage, test review, are tests sufficient, generate tests, test gen, coverage

When NOT to Use

• Code review (use `codex-code-review`)
• Document review (use `doc-review`)
• Just want to run tests (use `/verify`)

Commands

| Command | Description | Use Case | | -------------------- | ----------------------- | ------------------- | | `/codex-test-review` | Review test sufficiency | **Required** | | `/codex-test-gen` | Generate unit tests | Add missing tests | | `/check-coverage` | Test coverage analysis | After feature dev |

Workflow: `/codex-test-review`

Smart detect target → Read test + source → Codex review (5 dimensions) → Coverage assessment + Gate → Loop if Needs additions

Step 1: Smart Detection

| Input | Behavior | |-------|----------| | File path | Review that file directly | | Directory | Review all tests in directory | | Description | Auto-find related test files | | Module name | Search related test files | | No parameter | Auto-detect from git diff |

Step 2: Read Test and Source

• Read test file (`TEST_FILE`)
• Read corresponding source (`SOURCE_FILE`, inferred from test path)

Step 3: Codex Review

**First review**: dispatch per `@skills/codex-code-review/references/codex-transport.md` § Start with the test review prompt. See `references/codex-prompt-test-review.md`.

**Loop review**: dispatch per § Resume with the re-review template. See `references/codex-prompt-test-review.md`. Rotation applies per the central contract (see § Review Loop below).

**`codex_fail` → fallback carries the gate** (adapter **exit 1** only — `@skills/codex-code-review/references/codex-transport.md` § Completion state machine: a pending or unknown completion keeps the gate **open** with no fallback, exit 2 is a configuration error, and an `alloc`/`cleanup` failure is a lifecycle error) (`@rules/auto-loop.md` § Review Dispatch): decide via `scripts/lib/review-dispatch.js` (`contract:'test:coverage'`), record `[REVIEWER_FALLBACK]`, dispatch `contract-neutral-reviewer` via Task with `references/codex-prompt-test-review.md` as the governing template (P3 = one retry, fresh instance), and validate the raw report with `node scripts/validate-family-sentinel.js test:coverage` before adopting the verdict. Carriers exhausted → no gate sentinel, behaviour-layer `⚠️ Need Human`.

**Save the returned `threadId`.**

Workflow: `/codex-test-review --ac-trace`

AC traceability mode — maps Acceptance Criteria from request docs to test evidence.

--ac-trace input → Read request doc → Parse ACs → Filter quality-gate → Search evidence → Codex verify → Matrix + Gate

Step 1: Input Resolution

| Input | Behavior | |-------|----------| | `--ac-trace <request-path>` | Read specified request doc | | `--ac-trace` (no path) | Auto-detect from `docs/features/*/requests/*.md` via git diff context | | No `--ac-trace` | Existing behavior (5-dimension coverage review) |

Step 2: Parse & Filter ACs

1. Locate `## Acceptance Criteria` section in request doc 2. Parse `- [ ]` / `- [x]` items 3. Filter out quality-gate ACs matching: `/codex-review-fast`, `/codex-review-doc`, `/codex-review`, `/precommit`, `/precommit-fast`, `/pr-review`

Step 3: Search Evidence

For each non-quality-gate AC:

| Evidence Type | Priority | How to Find | |--------------|----------|-------------| | Automated test | 1 (preferred) | Search Related Files test paths; match AC text → test assertions | | Runtime verification | 2 | Search `/feature-verify` results at L3+ confidence | | Manual exception | 3 (verified only) | Check AC annotation `<!-- exception: REASON, expires: DATE -->` |

Step 4: Codex Verify (independent)

Fresh thread (§ Start). See `references/codex-prompt-ac-trace.md`.

| Rule | Detail | |------|--------| | Cache | `request-path + git diff hash` key; same session reuse | | `codex_fail` — adapter **exit 1 only** (`@skills/codex-code-review/references/codex-transport.md` § Completion state machine: pending/unknown keeps the gate open with no fallback; exit 2 is a configuration error; `alloc`/`cleanup` failures are lifecycle errors) | Fallback carries the verification (`@rules/auto-loop.md` § Review Dispatch): decide via `scripts/lib/review-dispatch.js` (`contract:'test:ac-trace'`), record `[REVIEWER_FALLBACK]`, dispatch `contract-neutral-reviewer` via Task with `references/codex-prompt-ac-trace.md` as the governing template (P3 = one retry, fresh instance); validate the raw report with `node scripts/validate-family-sentinel.js test:ac-trace` before deriving the public sentinel | | Carriers exhausted | No validated raw report exists, so **no raw or public AC gate sentinel is derived** — mark all items `⚠️ Inconclusive` in the body and surface behaviour-layer `⚠️ Need Human` only (whatever the mode); note nothing |

**Save the returned `threadId`.**

Step 5: Exception Validation (3-gate)

| Gate | Check | |------|-------| | Reason class | Closed enum: `ENV_UNAVAILABLE` / `UNSAFE_TO_AUTOMATE` / `ONE_TIME_MIGRATION` | | Codex verification | Must emit `VALID_EXCEPTION` | | Expiry | ISO 8601; expired = ⛔ (strict) or ⚠️ (advisory) |

**Exception caps** (from @rules/testing.md): 1-8 AC = max 1; 9-12 = max 2; 13+ = hard cap 2. **Prohibited domains**: Security AC, Data-integrity AC, Regression AC = no exceptions allowed.

Step 6: Output + Gate

Gate sentinels (from @rules/testing.md). These public forms are **derived** from the raw report's `gate:` line — `gate: Adequate` → `✅ Adequate`, `ga