test-review · git:20260318.e45e7b4 · 2026-03-18 · sha256 036b05c593c1a99d
test-review git:20260318.e45e7b4A
Immutable. This exact content is served forever at /api/v1/blob/036b05c593c1a99d.
---
name: test-review
description: "Test coverage review via Codex MCP. 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: mcp__codex__codex, mcp__codex__codex-reply, Bash(git:*), Read, Grep, Glob, Write
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**: `mcp__codex__codex` with test review prompt. See `references/codex-prompt-test-review.md`.
**Loop review**: `mcp__codex__codex-reply` with re-review template. See `references/codex-prompt-test-review.md`.
Config: `sandbox: 'read-only'`, `approval-policy: 'never'`
**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 (`mcp__codex__codex`). See `references/codex-prompt-ac-trace.md`.
| Rule | Detail |
|------|--------|
| Cache | `request-path + git diff hash` key; same session reuse |
| Timeout | 30s → fallback to Claude-only + `⚠️ Inconclusive` |
| Unavailable | All items `⚠️ Inconclusive`; advisory → `⚠️ Adequate with exceptions`; strict → `⚠️ Need Human` |
Config: `sandbox: 'read-only'`, `approval-policy: 'never'`
**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):
| Sentinel | Meaning |
|----------|---------|
| `✅ Adequate` | All ACs covered by evidence |
| `⚠️ Adequate with exceptions` | Validated exceptions within cap |
| `⚠️ Need Human` | Codex unavailable or 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
1. Read source file
2. Derive test path: `src/service/xxx.ts` → `test/unit/service/xxx.test.ts`
3. Codex generates tests. See `references/codex-prompt-test-gen.md`.
4. Save to target path
5. 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.
Max 3 rounds. Still failing → report blocker.
## Output
```markdown
## Test Coverage Review
| Dimension | Coverage | Rating |
|-----------|----------|--------|
| ... | ... | ⭐1-5 |
### Gate: ✅ Tests sufficient / ⛔ Needs additions
```
## Verification
- [ ] Coverage assessment includes all dimensions
- [ ] Gate is clear (✅ Tests sufficient / ⛔ Needs additions)
- [ ] 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
```