Team Review Tests

Team Review Tests#

Run a team-based test quality review with platform-neutral multi-persona orchestration, producing a findings register with severity ratings and recommendations.

Note

Generated artifacts use the platform orchestration adapter. Claude can use agent teams where available; Codex and OpenCode ask before subagents and otherwise use the sequential persona fallback.

Description#

The team-review-tests skill spawns 3 test-quality-specialist judges who independently review test code from their specialist perspective. Each persona operates in a separate context window, ensuring independent analysis. Judges then debate their findings across rounds before producing a consolidated findings register.

This is the team-based equivalent of the standalone review-tests skill. Use it for important test suites where false confidence from weak tests could mask real defects.

Relationship to review-tests:

  • review-tests runs as a single agent in one context window

  • team-review-tests spawns 3 independent judges with separate context windows for deeper, multi-perspective analysis

Relationship to pre-mortem:

  • Pre-mortem uses platform-native persona orchestration for failure analysis of plans

  • Team-review-tests uses platform-native persona orchestration for test quality analysis of code

Both follow the same platform-native persona orchestration workflow pattern.

Triggers#

The skill activates when you mention:

  • Team-based test review

  • Multi-judge test audit

  • Team test quality review

Explicit invocation:

/wf:team-review-tests

Default Judges#

The skill uses 3 complementary test-quality-specialist judges:

#

Name

Perspective

1

Correctness Analyst

Circular/cheating tests, tautological assertions, production logic reuse in expected values, tests that cannot fail

2

Coverage Analyst

Missing boundary tests, untested error paths, weak assertions, missing end-to-end scenarios, assertion quality

3

Isolation Analyst

Shared mutable state between tests, over-mocking, nondeterminism (time, randomness, network), test data coupling to production data

These judges can be overridden via frontmatter, but the defaults are designed to cover complementary test quality domains and overriding is not recommended.

Input Format#

The skill uses a hybrid input model: paths are required, an optional markdown brief provides additional guidance.

Paths (required):

Paths to test files or directories can come from:

  1. Inline with invocation (e.g., /wf:team-review-tests tests/)

  2. scope frontmatter field in the brief file

  3. Body of the brief file

Brief (optional):

An optional markdown brief provides guidance. Located via:

  1. Explicit path with using (e.g., using review-brief.md)

  2. the platform default input file in the repository root

  3. If not found, the skill proceeds without a brief

Frontmatter Fields#

All fields are optional. Defaults are applied when not specified.

Field

Type

Default

Description

judges

list

3 test specialists

Override default analysts (not recommended)

rounds

int

2

Number of inter-judge debate rounds

verdict_threshold

int

3 (unanimous)

Judges that must agree for PASS

output_dir

string

"resources/agent-docs/reviews/tests"

Where transcripts are written

context_budget_kb

int

100

Max total KB for embedded @file context

scope

list

none

Paths to test files or directories

review_round

int

auto-detect

Override the detected review round number

Key differences from pre-mortem defaults:

  • 3 judges (vs pre-mortem’s 4) — test review has 3 natural domains

  • Unanimous threshold — same conservative approach

  • Separate output directory — resources/agent-docs/reviews/tests/

Example Frontmatter#

Minimal (paths only, no brief needed):

/wf:team-review-tests tests/

With brief file:

---
scope:
  - tests/
  - integration_tests/
---

# Review Auth Tests

Focus on JWT token handling. The production code is in @src/auth/tokens.py.

@file Auto-Detection#

Same mechanism as the council and pre-mortem skills. The skill scans the brief body for @path/to/file references and embeds their contents into judge prompts.

See the Council documentation for full details on detection rules and embedding logic.

Production Code Auto-Discovery#

Unique to this skill: test files are analysed for imports to automatically discover and embed the production code under test. This gives judges the full picture without requiring manual @file references for every production module.

Context budget priority:

  1. Test files — always included (review target)

  2. Production files — included if budget allows

  3. ``@file`` references — included if budget allows

Reviewer Identity and Review Rounds#

Each report records who produced it and which iteration of the review it is, so a directory of reports stays readable after several rounds and across several models.

Warning

Two different things are called “rounds”. The rounds frontmatter field is the number of debate rounds — how many times the judges exchange assessments inside a single review. The review round is the Nth time this scope has been reviewed at all. The transcript labels them **Debate Rounds:** and **Review Round:** respectively.

Reviewer identity#

The reviewing model self-reports its own identifier. The reasoning effort level is resolved from, in order:

  1. A reasoning-effort environment variable exposed by the host runtime, if one is set (for example CLAUDE_EFFORT on Claude Code)

  2. The host runtime’s own configuration, if readable

  3. Otherwise unknown

Either value falling back to unknown never blocks the review. Only the session model is tagged — judges inherit it, so they are not queried individually.

Review round detection#

The round counts iterations over the same scope, regardless of which agent or model ran each one. A round 2 review run by Codex legitimately follows a round 1 review run by Claude — the series belongs to the scope under review, not the reviewer.

Detection reads existing output_dir/team-review-tests-*.md reports, keeps those whose **Scope:** paths overlap this review’s scope, and takes the highest **Review Round:** value plus one. With no prior matching reports the review is round 1. Reports written before round tagging existed count as round 1, so the next tagged report becomes round 2.

Scopes overlap when any pair of resolved paths is equal, or when one path is a directory containing the other:

Prior scope

Current scope

Result

tests/auth/

tests/auth/

Same series (equal)

tests/auth/

tests/auth/, tests/api/

Same series (overlap)

tests/auth/

tests/auth/test_login.py

Same series (contained within)

tests/auth/

tests/billing/

New series (no overlap)

Note

Overlap matching errs towards continuing a series, so a broad tests/ review and a narrow tests/auth/ review are treated as one series even if you meant them to be separate. The skill reports which prior reports matched; set review_round in frontmatter to force a different number.

Prior rounds are summarised in a Prior Review Rounds table at the top of the new report, showing each earlier round’s date, model, effort and verdict.

Output naming#

Reports are named round-first so iterations of one scope sort together:

team-review-tests-r01-2026-07-30-143000-opus-5-high.md
team-review-tests-r02-2026-07-31-091500-opus-5-high.md
team-review-tests-r03-2026-08-01-160000-sonnet-5-medium.md

The round is zero-padded to two digits. The model and effort slugs are lowercased with non-alphanumeric runs collapsed to single hyphens.

Workflow#

  1. Parse paths and optional brief

    • Locate paths from invocation, scope frontmatter, or brief body

    • Parse optional brief file for frontmatter and guidance

    • Apply defaults (rounds=2, threshold=unanimous)

    • Resolve the reviewer model, effort level and review round

  2. Gather test files from scope

    • Search directories for common test patterns

    • Stop if no test files found

  3. Map tests to production code

    • Analyse imports to build test-to-production-code map

    • Locate production source files

  4. Embed context

    • Include test files, production files, and @file refs within budget

    • Condense large files via smart_read

  5. Configure judges

    • Use 3 default test-quality specialists (unless overridden)

  6. Create agent team

    • Start a session-scoped persona execution run

    • Lead coordinates all communication and writes output files

  7. Spawn judges and seed context

    • Each persona receives test code, production code, role instructions, and the false-confidence framing

    • Each persona produces initial assessment with findings

  8. Execute debate rounds

    • For each round, each judge receives all other judges’ latest responses

    • Judges look for finding interactions, missed issues, insufficient suggestions

  9. Consolidate verdict and build findings register

    • Apply conservative verdict logic

    • Build findings register table from all findings

    • Produce recommendations by severity

  10. Clean up agent team

    • Cleanup runs unconditionally, even on error

  11. Write transcript

    • Write to output_dir/team-review-tests-rNN-YYYY-MM-DD-HHMMSS-<model>-<effort>.md

Verdict Logic#

Team-review-tests uses conservative verdict logic (same as pre-mortem):

  • FAIL if ANY judge finds tests giving false confidence

  • WARN if issues exist but tests are not actively misleading

  • PASS only if ALL judges agree test quality is sufficient

This means a single judge finding false-confidence tests produces an overall FAIL verdict.

Findings Register#

The transcript includes a consolidated findings register table:

| # | Finding | Analyst | Severity | File:Line | Suggestion | Status |
|---|---------|---------|----------|-----------|------------|--------|
| 1 | Expected value uses parse() (circular) | Correctness | HIGH | tests/test_parser.py:42 | Hand-craft expected dict | ADDRESSED |
| 2 | No test for empty input | Coverage | MEDIUM | tests/test_utils.py:18 | Add parametrised edge case | ADDRESSED |

Status values:

  • ADDRESSED — the suggestion provides a clear fix

  • ACCEPTED — finding acknowledged, risk is acceptable (LOW severity)

  • UNADDRESSED — no adequate fix identified (triggers FAIL if HIGH)

Recommendations#

The transcript organises recommendations by urgency:

  • Immediate Actions — from HIGH-severity findings; tests giving false confidence that must be fixed

  • Suggested Improvements — from MEDIUM-severity findings; should be planned

  • Noted — LOW-severity findings; documented for awareness

Transcript Format#

# Test Review Report — Round 2

**Topic:** Review Authentication Tests
**Scope:** tests/, integration_tests/
**Date:** 2026-02-21 14:30:00
**Review Round:** 2
**Reviewer:** opus-5 (effort: high)
**Debate Rounds:** 2
**Verdict Threshold:** 3 of 3 (unanimous)

## Prior Review Rounds

| Round | Date | Reviewer | Effort | Verdict | Report |
|-------|------|----------|--------|---------|--------|
| 1 | 2026-02-20 09:10:00 | sonnet-5 | medium | FAIL | team-review-tests-r01-2026-02-20-091000-sonnet-5-medium.md |

## Analysts

| # | Name | Perspective | Final Verdict |
|---|------|-------------|---------------|
| 1 | Correctness Analyst | Circular tests, false confidence | WARN |
| 2 | Coverage Analyst | Gaps, weak assertions | FAIL |
| 3 | Isolation Analyst | Shared state, nondeterminism | WARN |

## Overall Verdict: FAIL

[summary referencing false-confidence findings]

## Findings Register

[consolidated table]

## Round 1
...

## Recommendations

### Immediate Actions
### Suggested Improvements
### Noted

## Verdict Summary

| Analysts PASS | Analysts WARN | Analysts FAIL | Threshold | Overall |
|---------------|---------------|---------------|-----------|---------|
| 0             | 2             | 1             | 3 of 3    | FAIL    |

Example Usage#

Review tests in a directory:

> /wf:team-review-tests tests/

Review specific test files:

> /wf:team-review-tests tests/test_parser.py tests/test_utils.py

Review with a brief for guidance:

> /wf:team-review-tests tests/ using review-brief.md

Review from default brief location:

> # Create the platform default input file with scope and guidance
> /wf:team-review-tests

Error Handling#

  • No paths provided: Asks the user for paths to test files

  • No test files found: Reports that no test files were found in scope

  • Platform-native persona orchestration unavailable: Use the generated sequential fallback and record the downgrade

  • Analyst fails to respond: Error recorded in transcript, remaining analysts continue

  • ``@file`` not found: Warning in transcript, file skipped

  • ``smart_read`` fails: File skipped, warning logged

  • Frontmatter parse error: Reports the YAML error and line number

  • Team cleanup fails: Warning logged, does not block output

  • Model or effort not resolvable: Tagged as unknown; review continues

  • Prior reports unlistable or unreadable: Treated as round 1, noted under Prior Review Rounds

  • Detected review round exceeds 99: Asks the user for an explicit review_round

Limits#

  • Judges: 3 default test-quality specialists. Override is possible but not recommended.

  • Rounds: 2 recommended. Test review benefits from cross-pollination but rarely needs more.

  • Token cost: 3 judges x (1 initial + 2 rounds) = 9 agent turns plus coordination overhead. Less expensive than pre-mortem (12 turns) but more than standalone review-tests. Reserve for important test suites.

  • Verdict threshold: Unanimous by default. Deliberately conservative.

  • Context budget: Default 100 KB. Set to 0 to disable file embedding.

  • Non-deterministic: Real output varies between runs.

  • One team per session: Do not run team-review-tests while another team is active.

When to Use team-review-tests vs review-tests#

Aspect

review-tests

team-review-tests

Agents

Single agent

3 independent judges

Cost

~1 agent turn

~9 agent turns

Depth

Good for quick audits

Deep multi-perspective analysis

Use when

Routine test checks

Important test suites, pre-release review

Requires

Nothing extra

Platform-native persona orchestration enabled
Contents