sd0xdev 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
- Locate
## Acceptance Criteriasection in request doc - Parse
- [ ]/- [x]items - 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, gate: Adequate_with_exceptions → ⚠️ Adequate with exceptions, gate: Need_Human → ⚠️ Need Human, gate: Inadequate → ⛔ Inadequate. Whoever produced the raw report (Codex or fallback carrier), the raw layer is what validate-family-sentinel.js test:ac-trace checks; this skill's derivation alone produces the public form:
| Sentinel | Meaning |
|---|---|
✅ Adequate |
All ACs covered by evidence |
⚠️ Adequate with exceptions |
Validated exceptions within cap |
⚠️ Need Human |
Every carrier exhausted (behaviour-layer only — never derived from a report), or the validated report is inconclusive |
⛔ Inadequate |
Unverified exception, cap breach, or prohibited domain |
Workflow: /codex-test-gen
Read source → Derive test path → Codex generate → Save test file → Suggest review
Steps
- Read source file
- Derive test path:
src/service/xxx.ts→test/unit/service/xxx.test.ts - Bind
FUNCTION_NAMEbefore rendering the prompt: the function named in the invocation, or the literalallwhen the caller supplied only a path —/codex-test-gen src/service/xxx.tsis the documented file-only form, so the placeholder must resolve to something. It used to carry its own default inside the template; nothing evaluates the template now, so the binding is the caller's and it is stated here. - Codex generates tests. See
references/codex-prompt-test-gen.md. - Save to target path
- Suggest: run tests then
/codex-test-review
Review Dimensions
| Dimension | Scoring Criteria | Weight |
|---|---|---|
| Happy path | All public methods, main flows | High |
| Error handling | try/catch, error callbacks | High |
| Edge cases | null/undefined, extremes, empty sets | Medium |
| Mock quality | Not excessive, not insufficient | Medium |
Three-Layer Tests
| Type | Directory | Mock | Focus |
|---|---|---|---|
| Unit | test/unit/ |
Full | Single function |
| Integration | test/integration/ |
Only external | Inter-module |
| E2E | test/e2e/ |
Prohibited | Complete flow |
Common Boundaries
| Type | Cases |
|---|---|
| String | "", " ", null, undefined, very long |
| Number | 0, -1, NaN, Infinity, MAX_SAFE_INTEGER |
| Array | [], [null], very large, nested |
| Object | {}, null, circular reference |
Review Loop
⚠️ @CLAUDE.md auto-loop: fix → re-review → ... → ✅ PASS ⚠️
⛔ Needs additions → add tests → /codex-test-review --continue <threadId> → repeat until ✅ Sufficient.
Thread rotation — central contract (@skills/codex-code-review/references/review-common.md § Review Loop — Thread Rotation): at the R-a threshold (3 replies on this thread; @rules/auto-loop-project.md ## Review Thread Rotation overrides, 2–6) or on R-b judged context overrun, dispatch the first-review template on a new thread instead of replying — no old findings fed, reconciliation orchestration-side — and record [THREAD_ROTATED].
Sentinel alias union (no canonicalization): ✅ Tests sufficient / ✅ Sufficient carry one pass semantic, ⛔ Tests need supplementation / ⛔ Needs additions one fail semantic. Both shapes stay legal exactly as written — nothing rewrites one into the other — and every report carries exactly one terminal (validate-family-sentinel.js test:coverage rejects mixing).
Max 3 rounds. Still failing → report blocker.
Output
## Test Coverage Review
| Dimension | Coverage | Rating |
|-----------|----------|--------|
| ... | ... | ⭐1-5 |
<findings and suggestions>
✅ Tests sufficient
The report ends with exactly one terminal, alone at column 0 on the final line, drawn from the
alias union above — pass: ✅ Tests sufficient or ✅ Sufficient; fail: ⛔ Tests need supplementation or ⛔ Needs additions. All four are legal exactly as written, which is why
this list must match the union rather than name a preferred pair: validate-family-sentinel.js test:coverage accepts all four, and the first-pass prompt emits ⛔ Tests need supplementation, so
a two-form list here would reject the template's own output. Never place two alternatives on one line.
Verification
- Coverage assessment includes all dimensions
- Exactly one gate terminal from the four-form alias union (
✅ Tests sufficient/✅ Sufficient/⛔ Tests need supplementation/⛔ Needs additions), alone at column 0 on the final line - Missing tests have specific code suggestions
- Codex independently researched source code branches
References
- Test review prompt:
references/codex-prompt-test-review.md - Test gen prompt:
references/codex-prompt-test-gen.md - AC trace prompt:
references/codex-prompt-ac-trace.md - Standards: @rules/testing.md
Examples
Input: /codex-test-review test/unit/service/xxx.test.ts
Action: Read test + source → Codex review → Coverage assessment + Gate
Input: /codex-test-gen src/service/xxx.ts
Action: Read source → Codex generate → Save test → Suggest review
Input: Are this service's tests sufficient?
Action: /codex-test-review → Assess coverage → Output gaps + Gate
Input: /codex-test-review --ac-trace docs/features/auth/requests/2026-03-01-login.md
Action: Parse AC → Filter quality-gate → Search evidence → Codex verify → Matrix + Gate