---
name: code-review-specialists
description: Decompose risky or broad diffs into read-only specialist review passes and merge normalized findings.
---

# Code Review Specialists

Use this workflow to review broad or risky diffs through focused, read-only specialist lenses before a reviewer makes a decision.

## Contract

Prereqs:

- Run inside the target git repository with `git` available on `PATH`.
- Know the base ref for the diff under review, or explicitly choose one before
  running scope detection.
- Keep this workflow read-only: it does not auto-fix code, merge, close PRs, or
  post live PR comments.
- Use explicit user instruction or a delegation mode such as `parallel-first` or
  `orchestrator-first` before spawning reviewer subagents.
- Use `dispatch-pr-review` for PR decision actions and `review-evidence` only when
  findings need a retained evidence record.

Inputs:

- Diff base ref, optional review target summary, and optional validation
  evidence to inspect.
- Optional forced specialist flags:
  `--testing`, `--security`, `--performance`, `--data-migration`,
  `--api-contract`, `--maintainability`, `--red-team`, or
  `--all-specialists`.
- Optional specialist JSONL finding files for deterministic merge and report
  synthesis.
- Optional confidence display threshold for merged findings.

Outputs:

- Scope JSON from the deterministic helper describing changed files, diff size,
  stack signals, test framework signals, and suggested specialists.
- Read-only specialist findings with concrete file or evidence anchors.
- A final specialist review report using
  `references/SPECIALIST_REVIEW_REPORT_TEMPLATE.md`.
- Optional `review-evidence` records when retained workflow evidence is needed.
- No source edits, PR comments, merge decisions, or close decisions from this
  workflow.

Exit codes:

- `0`: helper command succeeded.
- `1`: helper command failed due to missing repository state, malformed input,
  invalid findings, or other runtime failure.
- `2`: helper usage error from `argparse`.

Failure modes:

- Base ref is missing or does not resolve in the target repository.
- Diff is too small or low-risk for specialist review and no specialist was
  forced.
- Specialist output is malformed JSONL, lacks required fields, uses unsupported
  severity values, or omits evidence anchors.
- Findings lack enough confidence or evidence to support a concrete issue; mark
  them as residual risk instead of presenting them as verified findings.
- Caller tries to use this workflow as a substitute for `dispatch-pr-review`,
  `review-evidence`, `browser-qa`, CI repair automation, or implementation work.

## Entrypoint

- `$AGENT_HOME/skills/workflows/code-review/code-review-specialists/scripts/review_specialists.py`

## When To Use

- The user explicitly asks for specialist code review.
- A PR or diff is large, risky, security-sensitive, migration-heavy, API-contract
  heavy, or broader than normal reviewer confidence.
- Normal tests are not enough to reason about cross-cutting risk.
- An issue or plan PR review needs supplemental specialist findings before the
  `dispatch-pr-review` decision path.

Do not use it for tiny diffs, ordinary implementation work, pure formatting or
doc-only changes unless requested, CI repair loops owned by `gh-fix-ci`, or
browser-facing checks owned by `browser-qa`.

## Workflow

1. Establish the review target and base ref.
2. Run deterministic scope detection:

   ```bash
   $AGENT_HOME/skills/workflows/code-review/code-review-specialists/scripts/review_specialists.py scope --base <ref>
   ```

3. If `diff_lines < 50`, skip specialist review unless the user forced a
   specialist or all specialists.
4. Select specialists:
   - Always consider `testing` and `maintainability` for larger diffs.
   - Consider `security` for auth changes or backend changes over 100 diff
     lines.
   - Consider `performance` for backend or frontend runtime changes.
   - Consider `data-migration` for migration, schema, or data transform changes.
   - Consider `api-contract` for route, controller, API schema, OpenAPI,
     GraphQL, or protocol changes.
5. Run selected specialist passes as separate review lenses. In default
   single-agent mode, the main agent performs the lenses sequentially. In
   delegated mode, dispatch read-only reviewer subagents only when explicitly
   allowed.
6. Write each finding as JSONL following
   `references/SPECIALIST_REVIEW_CONTRACT.md`. Cite concrete file, line, diff,
   command, or evidence anchors when available. Mark unverifiable claims as
   residual risk, not findings.
7. Merge findings:

   ```bash
   $AGENT_HOME/skills/workflows/code-review/code-review-specialists/scripts/review_specialists.py merge-findings findings.jsonl --summary-out specialist-review.md
   ```

8. Run `red-team` only after selected specialists when `diff_lines > 200`, any
   selected specialist produced a `critical` finding, or the reviewer forced it.
   Merge red-team findings into the final report.
9. Use the report template for the final synthesis. The recommended next step
   may route to `dispatch-pr-review`, a normal implementation workflow, or a
   retained `review-evidence` record, but this workflow does not execute that
   decision.

## References

- Specialist review contract:
  `references/SPECIALIST_REVIEW_CONTRACT.md`
- Report template:
  `references/SPECIALIST_REVIEW_REPORT_TEMPLATE.md`
- Specialist prompts:
  `references/specialists/`
- PR decision workflow:
  `skills/workflows/issue/dispatch-pr-review/SKILL.md`
- Review evidence tool:
  `skills/tools/workflow-evidence/review-evidence/SKILL.md`
