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

.. code-block:: text

   /wf:team-review-tests

Default Judges
--------------

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

.. list-table::
   :header-rows: 1
   :widths: 5 25 70

   * - #
     - 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.

.. list-table::
   :header-rows: 1
   :widths: 20 10 15 55

   * - 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):**

.. code-block:: text

   /wf:team-review-tests tests/

**With brief file:**

.. code-block:: yaml

   ---
   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 :doc:`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:

.. list-table::
   :header-rows: 1
   :widths: 30 30 40

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

.. code-block:: text

   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:

.. code-block:: markdown

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

.. code-block:: markdown

   # 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:**

.. code-block:: text

   > /wf:team-review-tests tests/

**Review specific test files:**

.. code-block:: text

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

**Review with a brief for guidance:**

.. code-block:: text

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

**Review from default brief location:**

.. code-block:: text

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

.. list-table::
   :header-rows: 1
   :widths: 20 40 40

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