multi-shot-review

複数ショットレビュー

1. ユーザーの権限に応じてモードを選択します。

• Barrier（デフォルト）：すべてのレビューをこのモードで開始します。
• Report：対象を変更しないレポートのみのレビューをユーザーが明示的に要求した場合に限り切り替えます。

2. ライブの Git 対象と、元の依頼の正確な内容を指定してレビューを初期化します。

SKILL_DIR="/path/to/this-skill"
REVIEW_DIR="$(python3 "$SKILL_DIR/scripts/init_state.py" \
  --uncommitted \
  --task-file - <<'EOF'
<original user request>
EOF
)"

適切な場合は、--base <branch> または --commit <sha> を使用します。状態には対象の記述子のみが保存され、分類器とレビュー担当者は Git を直接確認します。$REVIEW_DIR/task.md にタスクのコンテキストが正確に記載されたら完了です。ユーザーが設定バリアントを明示的に求めた場合に限り、--variant <tag> を追加します。

3. クリーンな分類器を実行します。

python3 "$SKILL_DIR/scripts/classify_slices.py" \
  --review-dir "$REVIEW_DIR"

これに参加させます（長時間実行への参加を参照）。設定済みの分類器プロファイルを上書きする場合に限り、--harness、--model、または --reasoning を使用します。

必要に応じて、ユーザーからの補足指示をそのまま --user-directives-file <path> で渡し、親のコンテキストを参考情報として --executor-context-file <path> で渡します。分類器は対象、タスク、ルール、コード、現在のスライス、トゥームストーン、実行履歴、履歴データを読み取ります。状況に応じて add_slice.py と remove_slice.py を呼び出します。分類計画の成果物はありません。 選択の動作はreferences/slice-selection.mdに記載されており、分類器によって読み込まれます。ランチャーは、グローバルおよび変更されたパスに適用されるレビュー指示チェーンを自動的に解決し、スコープ付きのコンテキストにまとめます。分類器は、適用されるレビュー方針を文言と適用範囲を保ったまま含め、各レビュー担当者向けの完全なプロンプトを作成します。レビュー方針がない場合は、コンテキスト上必要な範囲でのみ、内容ごとに分割した広範なレビューを使用します。レビュー担当者は補助的なコンテキストを参照できますが、割り当てられた変更のみを報告します。

スライスがない状態で終了コード 2 が返された場合は、再試行する前に $REVIEW_DIR/_logs/classifier-<id>.stdout.log を読みます。子プロセスがブロックされた理由を説明しています。 スライスの作成後に分類に失敗した場合は、レビューを開始する前に分類を完了するため、--resume-incomplete を使用します。このオプションを使うには、分類に失敗しており、それ以前に分類が成功しておらず、レビュー実行もないことが必要です。不完全なスライスのセットを保持し、現在の分類器を使って完了します。レビュー後に新たな分類を行うことはできません。

分類はセッションごとに 1 回だけ実行します。セッションにアクティブなスライスがある場合、classify_slices.py は失敗します。ユーザーの指示によってすべてのスライスが削除された後は、分類器を再実行できます。スライスのセットは、ユーザーによる明示的なスライス変更を通じてのみ変更します。それ以外の場合は、不完全なスライスを再実行します。

4. レビューを 1 ウェーブ実行し、その後参加させます。ウェーブの最終 JSON を取得したら完了です。

python3 "$SKILL_DIR/scripts/run_reviews.py" --review-dir "$REVIEW_DIR" \
  --child-timeout-seconds 3600

実行可能なすべてのスライスを 1 つのウェーブで実行します。同時に実行される子プロセスは最大 max_parallel 個で、残りの子プロセスはキューで待機します。shots > 1 のスライスでは、同じプロンプトを使う独立したレビュー担当者のショットを、その数だけウェーブ内で実行します。兄弟ショットがすでに報告した指摘は、ランナーによって自動的に重複としてマークされます。レビュー担当者は references/review-result.schema.json に定められた厳密な JSON 形式を出力します。ランナーはこれを検証して、セッション内で一意の f_ ID を割り当て、生の結果を生成された Markdown に置き換えます。無効な結果は、再試行可能なスライス失敗になります。out 内の最終 JSON、指摘 ID、Markdown パスのみを使用し、err 内の診断情報を確認します。各 out レコードにはショットが sh で記載され、final が含まれます。各指摘は仮説として扱い、コードとタスクに照らして検証します。

5. 選択したモードを完了します。

Report

検証済みの統合された指摘を、ファイルと行の参照情報とともに返します。スライスの失敗はレビュー範囲の対象外として記載します。ok は実行の成功、rem はフォローアップ対象になり得ることを示すものとして解釈します。rem の値にかかわらず、ウェーブの結果を確認したら Report モードを完了します。

フォローアップを要求された場合は、別のウェーブを実行します。適格なスライスを実行するには同じセッションを再利用し、希望する対象範囲が変わった場合は、ユーザーによる明示的なスライス変更を適用します。すべてのスライスを独立して再実行する場合、または対象を変更する場合は、新しいセッションを初期化します。

バリア

検証済みの指摘を修正し、リスクを大きく減らせる場合は、対象を絞った回帰テストを追加します。却下した指摘を 1 件、変更できない理由とともに無視します。

python3 "$SKILL_DIR/scripts/ignore_finding.py" \
  --review-dir "$REVIEW_DIR" \
  --id "<finding-id>" \
  --reason "<why it is not actionable>"

より長い理由には --reason-file <path> を使用します。繰り返しの指摘は、現在オープンになっている別の指摘の重複としてマークします。

python3 "$SKILL_DIR/scripts/dedupe_finding.py" \
  --review-dir "$REVIEW_DIR" \
  --id "<duplicate-id>" \
  --canonical-id "<open-finding-id>"

修正後に次のウェーブを実行します。最新のウェーブにあるすべての指摘が無視または重複として処理された場合も、スライスは完了します。

各スライスには max_passes 回（デフォルトは 3）のパス予算があります。予算を使い切っても指摘が残っている場合、次の run_reviews.py 呼び出しでは、ウェーブの前にそのスライスの判定を新たに実行します。JSON の judge 配列には、それぞれの理由を含む判定が列挙されます。

• continue：スライスに、さらに max_passes 回分の期間が与えられました。判定プロンプトでは、設計上の継ぎ目または修正品質の問題を具体的に示す理由を求めます。ランナーは理由のテキストを検証しません。次のウェーブの前に、その理由に対応してください。
• stop：スライスは完了です。最終ウェーブの指摘は "final":true を付けて out に返されます。その指摘は、次のウェーブを実行せずにすべて修正するか、無視してください。

判定に失敗すると、"st":"judge_failed" を含む err レコードが返され、スライスは変更されません。再試行するには run_reviews.py を再実行してください。判定ルールと矛盾する判定（どちらの方向も）は、判定の失敗として扱われます。すべての非最終指摘が修正済みまたは終端として記録され、すべての final 指摘が修正または無視され、関連するチェックが合格し、JSON が "ok":true および "rem":0 を返したら完了です。

長時間実行への合流

classify_slices.py と run_reviews.py は 1 時間以上かかる場合があります。それぞれを起動したら、次の手順に進む前に合流し、最終 JSON を受け取ってください。ハーネスが提供する中で、最も効率のよい合流方法を選びます。まず終了通知付きのバックグラウンド実行を試し、最後に最長タイムアウトのフォアグラウンド実行を試してください。

合流が完了するまでは、レビュー対象を 変更せずに保ちます。レビュー担当者は Git の最新状態を読み取ります。レビュー用ディレクトリごとにスクリプトを 1 つだけ実行し、終了するまで待ちます。

ウェーブの合流が中断された場合（デタッチ、タイムアウト、セッション消失）は、次のコマンドで再接続します。

python3 "$SKILL_DIR/scripts/await_reviews.py" --review-dir "$REVIEW_DIR"

ユーザーによる明示的なスライス変更

親からの変更が許可されるのは、ユーザーが明示的に依頼した場合に限ります。references/classifier-rules.md のレビュアープロンプトの契約に沿って完全なプロンプトを指定し、その依頼を保持してください。

python3 "$SKILL_DIR/scripts/add_slice.py" \
  --review-dir "$REVIEW_DIR" \
  --name "<slice-name>" \
  --harness "<harness>" \
  --prompt-file "<prompt-file>" \
  --user-directive-file "<verbatim-user-request-file>"

--shots <n> は、パスごとに並行して実行するレビュアーの回数を設定します。省略すると、設定済みのデフォルトが使用されます。保持対象の指摘を返さなかったショットは、そのスライスの後続ウェーブでショット数を 1 回減らします（最小 1 回）。--shot-passes <n|always> は、スライス定義を起点に数えて、複数のショットを実行するパス数を設定します。それ以降のパスでは、ショットを 1 回だけ実行します。省略すると、設定済みのデフォルト 1 が使用されます。

同じ権限マーカーを使ってスライスを削除します。

python3 "$SKILL_DIR/scripts/remove_slice.py" \
  --review-dir "$REVIEW_DIR" \
  --name "<slice-name>" \
  --user-directive-file "<verbatim-user-request-file>"

削除するとスライスは tombstone 状態になります。同じ名前で再追加すると、再び有効になります。定義は変更できますが、実行、出力、履歴は保持されます。再有効化されたスライスには、新たな max_passes の期間が与えられます。

状態、ロック、出力名、レンダリング、再試行、完了の管理は、すべてスクリプトのみが行うものとして扱ってください。生成されたレビュー用 Markdown は編集しないでください。