研究レビュー（Research Review）

研究レビュー（モジュール式＆結合レビューゲート）

Plan、Coding、Test はスタンドアロンまたは結合して実行できます。

• 計画のみを立てた場合 → **モード A（プランレビュー）**を実行します。
• コードを書き、すぐにテストを書いて実行した場合（自然な流れ） → **モード B+C 結合（コード＆テストジョイントレビュー）**を1回の並列レビューラウンドで行います。2回の個別レビューラウンドを連続して実行するのは時間の無駄です。
• テストを書かずにコードのみを書いた場合、または既存コードに対してテストのみを書いた/実行した場合 → モード B または モード C をスタンドアロンで実行します。

1. レビュアーサブエージェントのディスパッチ（spawn_subagent）

• デフォルトレビュアー (channel=mcli): spawn_subagent を同時に呼び出して2つの並列レビュアーを起動し、get_command_or_subagent_output で両方の完了を待ちます。
  • サブエージェント 1: model: "deepseek-v4.1-flash" (mcli チャネル)
  • サブエージェント 2: model: "glm-5.3" (mcli チャネル)
• ユーザーオーバーライド: ユーザーが他のモデル（例：kimi-k3.1-pro、MiniMax-M3.1-Flash、deepseek-v4-pro、または friday/* / catpaw-ide/* スラッグ）を指定した場合、ユーザー指定の model スラッグを spawn_subagent に渡します。
• 増分クロージャー (resume_from)：
  • 発見（ラウンド 1）: 最小限の成果物（Plan、git diff、テストコード＋実行 stdout/stderr）と主要ファイルパスのみで新しいサブエージェントを起動します。会話履歴は決して渡さないでください。
  • クロージャー（ラウンド 2 以降、修正や追加テストが必要な場合）: 各レビュアーに対して resume_from: "<subagent_id>" を指定して spawn_subagent を呼び出し、アクティブな発見事項と修正/テスト差分のみを渡して、変更されていないファイルを再度読み込むことなく更新を検証させます。

2. コアロール境界

1. メインエージェントが先に検証を実行: レビュアーをディスパッチする前に簡単な構文/スモークテストを実行することを推奨します。これにより、レビュアーが壊れた構文に労力を浪費するのを防げます。正確なテストコマンドとその出力を「メインエージェント検証証拠」として渡します。
2. 厳格な読み取り専用レビュアー: レビュアーサブエージェントには、ファイルの読み取り/grep のみを実行し、file:line の証拠を付けて重要度順に発見事項を報告し、未テストのエッジケースに対しては - Validation request: <正確なチェック内容> を出力するように指示します。レビュアーは決してファイルを編集したりコマンドを実行したりしません。
3. メインエージェントによる裁定: 編集を開始する前に、起動したすべてのレビュアーが完了するのを待ちます。候補となるバグを独立して再現し、有効な Validation request を実行し、具体的なコードまたは数学的証拠に基づいて裁定（accepted / rejected）を行います。

---

モード A: プランレビュー（スタンドアロン）

1. 準備: 目的、変更対象ファイル、テンソル形状/データフロー、および明示的な前提条件（訓練セマンティクス、報酬スケール、ベースラインの公平性に影響を与える未表明の選択）を記述します。
2. レビュアーへのプロンプト:

   「この研究計画を読み取り専用でレビューしてください。ファイルを編集したりコマンドを実行したりしないでください。未表明の前提条件に異議を唱え、データ/ラベル漏洩、ベースラインの不公平性、分散/ロールアウトのボトルネックをチェックしてください。Review coverage: FULL|PARTIAL - <検査済みファイル> を記載し、Review verdict: APPROVED|FINDINGS で締めくくってください。[計画と主要ファイルパスを挿入]」

モード B: コーディングレビュー（スタンドアロン — テストがまだ書かれていない場合）

1. 準備: 要件/計画の要約と git diff を収集します。
2. レビュアーへのプロンプト: 変更されたファイルとワンホップの呼び出し元を読み取り専用で検査し、サイレントな研究バグを探すように指示します。
   • マスキングとアラインメント: SFT/RL プロンプト対応答トークンマスクのオフバイワンエラー、パディングサイドの不一致、EOS/トランケーション処理。
   • テンソル形状とブロードキャスティング: 意図しないブロードキャスト（例：(B, 1) 対 (B,)）、次元削減エラー（系列対バッチでの mean/sum）。
   • 勾配と状態の衛生: 誤った detach()/no_grad()、KL の方向、アドバンテージ正規化のスコープ、ロールアウト全体でのエージェント環境状態のリセット漏れ。
   • Review coverage と Review verdict: APPROVED|FINDINGS を必須とします。

モード C: テストレビュー（スタンドアロン — 既存コードにテストを追加/監査する場合）

1. 準備: テストファイルのパス、対象モジュールのパス、および実際のテスト実行 stdout/stderr を収集します。
2. レビュアーへのプロンプト:

   「このテストとその実行出力を読み取り専用で監査してください。ファイルを編集したりコマンドを実行したりしないでください。コアとなる数学的/テンソル不変条件とエッジケースを実際に検証していますか？それとも、実際のロジックをモックで置き換えたり、アサーションを弱めて通過させていませんか？エッジケースが未テストの場合は - Validation request: ... を出力してください。Review coverage を記載し、Review verdict: APPROVED|FINDINGS で締めくくってください。」

モード B+C: コーディング＆テスト結合レビュー（メインエージェントが一度にコードを書き、自己テストした場合）

1. 準備: 要件/計画の要約、実装＋テストの git diff、および「メインエージェント検証証拠」（実行した正確なテストコマンドとその stdout/stderr）をパッケージ化します。
2. レビュアーへのプロンプト:

   「実装差分とメインエージェントの自己テストを読み取り専用で結合レビューしてください。ファイルを編集したりコマンドを実行したりしないでください。

   1. コードチェック: 変更されたファイルとワンホップの呼び出し元でサイレントな研究バグを探してください（トークンマスクのオフバイワン、パディング/EOS アラインメント、意図しないテンソルブロードキャスト (B,1) 対 (B,)、誤った削減次元、誤った detach()/no_grad()、KL/アドバンテージの数学、ロールアウト状態のリセット漏れ）。
   2. 自己テスト監査: メインエージェントのテストがこれらの不変条件とエッジケースを実際に検証しているか、それとも確証バイアス（ハッピーパスのみのテスト、コアロジックのモック化、弱いアサーション）に陥っていないかをチェックしてください。欠落しているエッジケーステストについては - Validation request: <正確なチェック内容> を出力してください。 Review coverage: FULL|PARTIAL - <検査済みファイル> を記載し、Review verdict: APPROVED|FINDINGS で締めくくってください。」

3. 裁定とクロージャー: 受け入れられたコードバグを修正し、有効な Validation request を満たします。重要な変更が行われた場合は、両方のレビュアーに対して resume_from を使用して差分を検証します。

---

3. 軽量台帳（docs/review-log.md）

各レビューゲートが完了した後、簡潔な5〜10行の英語エントリをカレントプロジェクトの docs/review-log.md に追記します（ファイルが存在しない場合は作成します）。これにより、コンテキスト圧縮を超えて subagent_id ハンドルを保持し、実験監査証跡を維持します。

## [YYYY-MM-DD] <短いタスクタイトル> (<モード A / B / C / B+C>)
- **前提条件/スコープ**: <主要な設計前提条件と変更ファイルの1行要約>
- **レビュアー**: `deepseek-v4.1-flash` (`id: <subagent_id>`)、`glm-5.3` (`id: <subagent_id>`)
- **裁定**:
  - `[ACCEPTED]` `<file:line>` — <簡潔なバグ/欠陥とその修正方法>
  - `[REJECTED]` `<file:line>` — <レビュアーの指摘が誤検出であった理由（数学/コード証拠付き）>
- **評決と証拠**: `APPROVED` (<1行のテスト/スモーク検証結果>)