review-team

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

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

When to Use / いつ使うか

• 重要リリース前の網羅的なレビューが必要なとき
• セキュリティ・バグ・テスト・依存関係を一度に確認したいとき
• 「どこから見ても問題ない」という確証が欲しいとき
• 単一視点のレビューでは不十分と感じるとき

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

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
• 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 扱いになる

Cost / コスト

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

他スキルとの関係

| スキル | 関係 |

| -------------------- | ---------------------------------------------------------------------------------- |

| adversarial-review | 補完: adversarial は「どう壊れるか」に特化。review-team は「網羅的な多視点」に特化 |

| river-review | 上位: river-review entry skill がロールを決定し review-team を起動する経路もある |