review-team

Review Team（レビュー・チーム）

複数の専門レビュアーロールを並列実行し、複数ロールが同一箇所を指摘した「コンセンサス指摘」を自動的に浮かび上がらせるレビュー手法。

When to Use / いつ使うか

• 重要リリース前の網羅的なレビューが必要なとき
• セキュリティ・バグ・テスト・依存関係を一度に確認したいとき
• 「どこから見ても問題ない」という確証が欲しいとき
• 単一視点のレビューでは不十分と感じるとき
• 実装前の設計書・仕様・計画を差分なしでレビューしたいとき（/review-team <path> でファイル全文を対象にする）

Reviewer Roles / レビュアーロール

ロール	担当領域	自動選択条件（auto モード）
bug-hunter	ロジックエラー・境界値・null/undefined 参照・並行アクセス競合・エラー握り潰し	常時
security-scanner	インジェクション・認証・機密漏洩	リスクファイルまたはインフラ変更
test-gap	テストカバレッジ・エッジケース	テストファイルまたはアプリファイル3件以上
dependency-reviewer	サプライチェーン・バージョンジャンプ	package.json / lockfile 変更
frontend-reviewer	アクセシビリティ・レンダリング・レスポンシブ・loading/error 状態の欠落	.tsx/.jsx/.css/.scss/.sass/.less/.vue/.svelte 変更
ci-cd-reviewer	ワークフロー・アクションのピン・権限	.github/workflows/ 変更

Stage / risk signal による選択（#1545 P1・任意）

auto モードは、上記のファイル種別ヒューリスティックに加えて、ホスト（PlanGate 等）が渡す 形式化された signal でもロールを選択できる。signal は任意で、渡さない場合の挙動は従来と不変（後方互換）。signal は既存ロールのみへ写像し、新ロールは作らない。写像先を持たない Lens（devex 等）は Reviewer Lens Taxonomy（Issue #1545）の Gap として記録され、レビュアーは追加しない。

signal 種別	追加ロール
stage: plan	security-scanner, test-gap
stage: design	frontend-reviewer
stage: exec / stage: release	security-scanner
stage: verify	test-gap
touchesAuth / changesPermissions / handlesSensitiveData	security-scanner
databaseMigration / breakingChange	security-scanner
changesUi / changesUserFlow	frontend-reviewer
deploymentChange	ci-cd-reviewer

選択理由（selectionReasons）と required / skipped の状態は run 結果の autoSelection に記録される。bug-hunter は常に required、選択されなかったロールは skipped に入る。

実装 SSoT: src/lib/reviewer-orchestrator.mjs の selectRolesAuto / computeAutoSelection。本表と実装は二重管理のため、片方を変更したら同一 PR で両方を整合させる。

Execution Flow / 実行フロー

Step 1: ロール決定
  ├─ 明示指定あり → 指定ロールを使用
  └─ 指定なし → auto（差分内容から最適ロールを自動選択）

Step 2: 並列実行
  [bug-hunter] [security-scanner] [test-gap] ...（同時起動）
       ↓
  Union-Find クラスタリングで重複 finding を統合

Step 3: consensusLevel の付与（finding ごと）
  agreement.length ≥ 3 → "consensus" ★★★
  agreement.length = 2  → "multi"     ★★
  agreement.length ≤ 1  → "single"    ★

Step 4: Tech Lead レポートの生成（追加 LLM コストなし）
  top3Findings    : consensusLevel → severity → scope 順の上位3件
                    （consensusLevel が severity に優先する。severity は
                      consensusLevel が同値のときだけ効き、scope は上位2キーが
                      同値のときだけ in-diff を先に置く）
  blindSpots      : 今回実行されなかったロール一覧
  consensusSummary: consensus / multi / single の件数集計

Output Fields / 出力フィールド

finding ごと

{
  "title": "SQLインジェクションの可能性",
  "severity": "critical",
  "consensusLevel": "consensus",
  "agreement": ["bug-hunter", "security-scanner", "test-gap"],
  "reviewerRole": "bug-hunter",
  "scope": "in-diff"
}

teamLeadReport（run 全体）

{
  "teamLeadReport": {
    "top3Findings": [...],
    "blindSpots": [{ "role": "frontend-reviewer", "label": "Frontend Reviewer" }],
    "consensusSummary": { "consensus": 1, "multi": 3, "single": 8, "total": 12 }
  }
}

Convergence Handoff / レビュー収束の判断

consensusLevel はレビュアー間の合意度です。指摘の真偽やループ終了を証明しません。

• 初回は変更範囲と必要な依存箇所を確認する。再レビューでは新しい差分を優先する。ただし認証や権限などの高リスク境界は省略しない。
• 前回と同じ指摘にはfinding identityと元の証拠を結び付ける。新しい証拠のない重複指摘を増やさない。未解決のcritical/majorは消さない。
• reviewCoverage が partial または not_executed の場合、指摘がゼロでも完了扱いしない。llmNotExecuted: true も同様に扱う。
• 3ラウンド続いて修正が必要なら、callerへ再計画を提案する。論点、再現手順、繰り返し指摘、レビュー対象を見直す。3ラウンドという値は停止条件ではない。
• STOP_OSCILLATED と ESCALATE_HUMAN は人間へ引き継ぐ。callerは STOP_MAX_ITERATIONS や費用上限を別途執行する。

River Reviewの役割は判定素材の提供までです。停止と再計画はcaller（PlanGate等）が担当します。判断規則はループ収束コントラクトを参照してください。

How to Run / 実行方法

River Review は npm パッケージを公開しない（プロジェクト方針）。したがって npx river-review は使えない。実行環境ごとに次の手段を使う。

プラグイン / エージェント環境（第一手段・CLI 不要）

Claude Code / Codex のプラグイン経由では、エージェントがこのスキルの手順を直接実行する。CLI は不要で、上記の Execution Flow（ロール決定 → 並列実行 → consensusLevel 付与 → Tech Lead レポート）をエージェント自身が再現する。

• スラッシュコマンド: /review-team、/review-team bug-hunter,security-scanner、または /review-team docs/design.md（ファイル全文が対象）
• CLI が無くても設計どおり動作する。CLI 実行を試みて失敗しても、スキル駆動のレビューで継続すること。

コントリビューター（リポジトリ内）

リポジトリ内では river CLI をアクセラレータとして使える（任意）。

# 差分から自動選択（推奨）
npm run river -- run . --reviewers auto

# ロールを明示指定
npm run river -- run . --reviewers bug-hunter,security-scanner,test-gap

# JSON 出力（teamLeadReport を含む）
npm run river -- run . --reviewers auto --output json

# コスト事前確認
npm run river -- run . --reviewers auto --dry-run

CLI は必須でない。存在しない、または失敗した場合はスキル駆動のレビューで継続する。

GitHub Actions

Actions では CLI が実行エンジンとして起動される。ワークフロー設定は Actions 用ドキュメントを参照する。

Output Interpretation / 結果の読み方

1. consensus 指摘を最優先で確認する — 複数の独立したロールが同箇所を指摘したため信頼度が最も高い
2. multi 指摘を次に確認する — 2ロールが合意した指摘
3. blindSpots を見て追加実行を検討する — 未実行ロールが多い場合はそのロールを追加して再実行
4. single 指摘はノイズ混入の可能性がある — ロール固有の観点からの指摘なので文脈に応じて判断
5. scope で対応範囲を切り分ける — in-diff は本 PR が追加行で持ち込んだ問題、pre-existing は変更ファイル内だが追加行の外にある既存コードへの指摘。pre-existing は文脈参考として扱い、本 PR のスコープを超えた修正を招かないようにする。値が無い場合は fail-safe で in-diff 扱いになる。ファイル全文が対象のときは区別が無く、すべて in-diff になる

Cost / コスト

• 実行ロール数 × 通常レビューコストが目安
• auto モードは差分に関係するロールのみを起動するため無駄がない
• Tech Lead レポートは追加 LLM コストなし（deterministic 計算）

他スキルとの関係

スキル	関係
adversarial-review	補完: adversarial は「どう壊れるか」に特化。review-team は「網羅的な多視点」に特化
river-review	上位: river-review entry skill がロールを決定し review-team を起動する経路もある