deep-review

Deep Review

実行可能な欠陥と改善点を特定し、選択されたハンクとプロジェクトルールの適用状況を漏れなく記録します。スクリプトが検出、分割、成果物の組み立て、検証を処理し、モデルが適用可否の判断と根拠に基づくレビューを行います。ソースは読み取り専用のままにし、レビュー成果物は <out>（デフォルトは .deep-review/<target>/）に書き込みます。このファイルから <skill-dir> を解決し、レビュー対象リポジトリのルートから同梱コマンドを実行します。

Contract

• PR のファイル数や行数に上限はありません。選択された各ハンクには、欠陥の担当者とポリッシュの担当者がそれぞれ 1 人ずつ割り当てられます。どちらもデフォルトでは、1 ジョブあたり200 ファイル／変更行 15,000 行の広いコホートを対象とし、--max-cohort-files、--max-cohort-lines、--max-polish-files、--max-polish-lines で調整できます。大きすぎるファイルはハンクを失わないよう分割されます。省略可能な --max-context-lines N の準備予算では、選択範囲を維持しながらファイル全体の読み込みを考慮します。
• すべての欠陥には因果関係を示す根拠が必要です。すべての助言には、観察された前提、具体的な改善案、範囲を限定した修正が必要です。調査の結果、却下した項目は抑制台帳に記録します。件数のノルマはありません。助言が SHIP を妨げることはありません。
• 適用するすべてのルールは、実際に読み込んだ内容に基づくものとし、原文、出典、適用範囲、明示的な評価を記録します。ルートおよびネストされた指示は、適用範囲と優先順位を維持します。メタデータはトリアージ用キューであり、すべてのスキルを読み込む指示ではありません。
• 関連するリンターを先に実行するか、同じ固定済み入力に対する根拠を再利用します。実行できないレーンを記録し、重複する指摘は抑制します。レーンを埋めるためにツールをインストールしてはいけません。
• チェックアウト、ルールの根拠、ジョブの契約は固定します。有効な出力は、契約に変更がない場合に限り再利用できます。網羅性の欠如、根拠の陳腐化、結果の形式不正がある場合は完了できません。
• 公開は --publish またはセッションで明示的に許可された場合に限ります。製品の修正はこのスキルの範囲外です。

1. 準備

python3 <skill-dir>/scripts/prepare_review.py --out <out> \
  [--pr N | --base REF | --staged | --worktree] [--files p1,p2] \
  [--spec PATH] [--full] [--max-cohort-files N] [--max-cohort-lines N] \
  [--max-polish-files N] [--max-polish-lines N]

ヘルパーはマニフェスト、knowledge.md、decisions.template.json を作成します。特にリベース後は、マニフェストの概要を確認して、base/head とファイル選択が正しいことを確かめます。選択対象が空の場合は、「レビュー対象なし」として終了します。PR の場合は、マニフェストの診断に従って不足している head/base/履歴を取得し、再試行します。

生のレジストリではなく knowledge.md を読みます。そのメタデータを使ってルーターを分類し、該当する指示とスキルの該当セクションを読みます。cp <out>/decisions.template.json <out>/decisions.json でテンプレートをコピーし、フィンガープリントを保持したまま、意味に関わる判断だけを編集します。簡潔なソース ID またはまとめた除外項目を使い、実際の理由、正確なルールの範囲、変更の意図、リンターの根拠を記載します。この入力契約（ルールレーンとレンズの対応付けを含む）については、context-pack.md — Decision file を参照してください。

python3 <skill-dir>/scripts/prepare_review.py --out <out> --decisions <out>/decisions.json

終了コード 2 は、未処理の判断が残っていることを示します。適用されたスキルの親項目が、次回のコンパイル時に参照先のルートを明らかにします。更新された decisions.template.json には、以前の判断と追加フィールドがすでに保持されています。これを decisions.json にコピーし、未処理の項目を編集します。参照先は、そのルーティング条件に基づいて評価します。親項目を除外すると、それに依存する参照先も処理済みになります。適用される親項目が必要としている間は、共有される参照先は未処理のままです。必須の参照先が不足している場合、準備はブロックされます。

判断を完了すると、rules.json、context-pack.md、パッケージ指向の plan.json、ジョブごとの契約、jobs.json がコンパイルされます。準備用のスクリプトを書いたり、パーティションを手作業で列挙したり、ディスパッチ前に手順書を作成したりしないでください。生成されたグループは、実際の意味上の境界がある場合に限り調整します。スイープはデフォルトで実行されません。具体的なコホート横断の仮説がある場合に限り、orchestration.md — Sweeps を使用します。--spec を指定すると、適合性スイープが自動的に追加されます。

2. レビュー

デフォルトではネイティブエージェントを使用し、同時実行数は最大 6 にします。ワーカーが受け取るのはレンダリング済みプロンプトのみです。「<prompt>を読み、割り当てられたレビューを完了し、そのプロンプト内のローカルコマンドでドラフトを提出してください。」対応している場合は、会話履歴を引き継がずに開始します（fork_turns=none）。ワーカーはこのスキル、グローバルなジョブ／マニフェストファイル、またはオーケストレーターの参照情報を読み込みません。ワーカーの契約には、必要なコンテキスト、ルール、ハンク ID、エビデンスの文法、出力形式が含まれています。

ワーカーは、明示的な評価を記入して提供されたドラフトテンプレートを埋め、その後、次を実行します。

python3 <skill-dir>/scripts/run_jobs.py --out <out> --job <label> --submit

これはそのジョブのみを検証し、ID を正規の出力に展開します。必須フィールドが欠落している場合や無効な場合は、ローカルで詳細な診断が出力されます。既存のドラフトを修正してください。一律の clear／compliant、ワーカー内でのグローバル検証、または JSON を再構築するためだけの新たな調査は行わないでください。

オーケストレーターだけが、バッチ処理後、または中断したラウンドを再開するために、グローバルゲートを実行します。

python3 <skill-dir>/scripts/run_jobs.py --out <out> --validate-only

promptフィールドを使って、保留中／無効なステータス行のみをディスパッチします。無効な行は、すでに対象を絞った修正プロンプトを指しています。有効な出力は再利用してください。進展のない失敗が繰り返される場合は、同じレビュー依頼を繰り返すのではなく、実際の診断内容を確認する必要があります。Workflow の実行については、orchestration.md — エンジンをお読みください。ネイティブ以外の --subagent については、subagent-runtimes.mdをお読みください。外部呼び出しでは compozy exec のクレジットを消費します。ユーザーが選択したモデル／effort を維持してください。

3. レポート

グローバル検証が 0 で終了した後、次を実行します。

python3 <skill-dir>/scripts/merge_findings.py --out <out>
python3 <skill-dir>/scripts/render_review.py --out <out> [--rework "<structural rationale>"]
python3 <skill-dir>/scripts/render_html.py --out <out>

レンダラーは、レポート生成時に計画、意図、レビュー担当者の要約からウォークスルーを作成します。不具合に基づいて SHIP／FIX_BEFORE_SHIP／REWORK を導き出し、勧告／抑制を保持して状態を書き込みます。レンダリングが成功した後にのみ判定結果を伝えてください。件数、すべての Critical／Major の不具合、カバレッジ、review.html のパスを含めてください。ReportFindings が利用可能な場合は、不具合を先に、その後に勧告を記載してください。表示を変更する場合、またはレポートの診断を解決する場合にのみ、output-contracts.mdをお読みください。

スコープ、設定、復旧

--base、--staged、--worktree、--files、--pr、--full は、マニフェストビルダーのスコープに関するセマンティクスを引き継ぎます。Worktree のレビューには未コミット／未追跡のファイルが含まれ、常に完全なレビューとなります。以前の状態がある場合、通常のラウンドでは増分処理が行われます。完全なラウンドを実行するには --full を指定します。--spec にはファイルまたはディレクトリを指定でき、判断項目で追加の正規アーティファクトを指定することもできます。

バッチの上限には正の整数を指定でき、PR が途中で切り詰められることはありません。準備処理では、選択した上限が判断ステージ、再開、更新を通じて prepare-request.json に保持されます。上限を再度指定した場合、その設定のみが上書きされます。直接実行する build_jobs.py はプランの上限を引き継ぎ、同じ4つのバッチフラグを受け付けます。

リポジトリの .deep-review.yaml にある path_filters、path_instructions、request_changes_workflow キーは、それぞれ個別に .coderabbit.yaml（reviews.*）へフォールバックします。組み込みの生成物／ベンダー／ロック／スナップショットの除外設定は引き続き適用されます。ルーブリックの優先順位は、パス別の指示、適用可能なプロジェクト指示のうち最も深いもの、ルートの指示、ルーティングされたスキル、学習内容の順です。

固定された入力を使って再開するには、--refresh を付けずに準備処理を再実行します。スコープまたはソースが変わった場合は、--refresh と新たな適用可能性の根拠が必要です。古いスナップショットを手動で承認してはいけません。プロバイダーによるブロックでは、ランナーが run-blocker.json とともに終了コード2を返します。利用可能な場合は、同じコマンドを再開してください。ランナーまたはグローバルの凍結では、古い入力を示す終了コード3が返されます。無効な入力では終了コード1が返され、アーティファクトの修復が必要です。カバレッジを回避してはいけません。prepare-status.json、ジョブごとのステータス、外部の試行ログで、モデル処理を追加せずに所要時間を確認できます。

--publish を指定する場合は、publish-github.md を読み、ローカルでレンダリングした後にその GitHub レシピを実行してください。ユーザーが指摘内容に反論した場合は、修正手順について state-and-learnings.md を読んでください。根拠または重大度の判断が不明確な場合に限り、taxonomy.md を読んでください。通常のレビュープロンプトには、必要な文法がすでに含まれています。