code-review-specialists

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:

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

   $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