consecutive-review-loop

consecutive-review-loop

サブエージェントによるレビュー＆修正ループを、N 回連続 PASS が達成されるまで繰り返す。途中で FAIL が発生した場合、streak カウンタは 0 にフルリセットされる。各サブエージェントレビューは、過去のフィードバックを一切含まないフラットプロンプトで起動しなければならない。

$ARGUMENTS

なぜ連続 PASS とフラットプロンプトが必要か

単発の PASS は弱い証拠である。サブエージェントが問題を見落とした可能性や、直前の修正が新たな問題を持ち込んだ可能性がある。N 回連続の独立した PASS は、成果物が健全であることのはるかに強い証拠になる。

連続 PASS を独立した証拠として数えるには、各レビューが過去のレビューについて一切知らないサブエージェントによって実施されなければならない。「これは 3 回目の試行で、前回のフィードバックは X, Y, Z でした」と伝えると、サブエージェントは過去の指摘にアンカリングし、新鮮な目で見ることをやめる。ループの意義が崩壊する。

パラメータ

ループ開始前に確定する。$ARGUMENTS で指定されていればその値を使い、なければデフォルト値を使用する。

• レビュー対象（必須）

  • デフォルト: なし
  • サブエージェントがレビューする成果物（ファイルパス、図、設計ドキュメント、コード変更など）

• レビュー観点（必須）

  • デフォルト: なし
  • サブエージェントに与える単一の観察フレーム（例: 「このシステム図は正確か？」）

• N（連続回数）

  • デフォルト: 3
  • 完了に必要な連続 PASS 回数

• PASS 基準

  • デフォルト: 「指摘事項なし」
  • レビューを PASS と判定する条件

• IF: 必須パラメータが不足 AND $ARGUMENTS から推論できない; THEN MUST: ループ開始前に AskUserQuestion でユーザーに確認する

ワークフロー

アルゴリズム（疑似コード）

function consecutiveReviewLoop(target, focus, N = 3, passCriterion = "指摘事項なし"):
    flatPrompt  := buildFlatPrompt(target, focus, passCriterion)   # 1回だけ構築、byte-frozen
    findingsLog := createFindingsLog(target)                       # append-only Markdown ファイル

    streak   := 0
    attempts := 0

    while streak < N:
        attempts += 1

        result := spawnSubagent(prompt = flatPrompt, model = "sonnet")
                    # 渡してはならないもの: streak, attempts, 過去の指摘, 過去の修正,
                    #                      "これは N 回目", "X に注意して" 等

        if result is malformed or subagent crashed:
            report("attempt #" + attempts + ": MALFORMED — 同一フラットプロンプトで再実行")
            continue                          # PASS にも FAIL にもカウントしない
                                              # 次のイテレーションで同じ flatPrompt を再実行

        verdict := classify(result, passCriterion)   # → PASS | FAIL

        if verdict == PASS:
            streak += 1
            report("attempt #" + attempts + ": PASS — streak " + streak + "/" + N)
        else:
            previousStreak := streak
            streak := 0                       # フルリセット — streak -= 1 ではない
            report("attempt #" + attempts + ": FAIL — streak reset "
                   + previousStreak + " → 0")

            for finding in result.findings:
                valid := triageFinding(finding)            # 妥当性判断: yes / no / partial
                fix   := if valid then applyFix(finding)   # メインエージェントが直接修正
                         else "no fix applied"
                appendToLog(findingsLog, attempts, finding, valid, fix)
            reverifyArtifactValid()            # compile / lint / preview 等

    report("DONE — " + N + " consecutive passes in " + attempts + " attempts")

実装が保持すべき 2 つの不変条件:

1. flatPrompt は 1 回だけ構築され、すべての spawnSubagent 呼び出しで byte-for-byte 同一のまま再利用される
2. イテレーション間でサブエージェント側に流れる状態は一切ない。メインエージェントが streak / attempts / 指摘事項を保持し、サブエージェントは成果物と観点だけを見る

Step 1: 状態の初期化

TodoWrite リストで以下の 3 項目を追跡する。すべてのイテレーションで更新する:

• streak: <current>/<N>

• attempts: <total>

• last result: <pass | fail | n/a>

• MUST: サブエージェント呼び出し後と修正完了後の両方で TodoWrite を更新する

Step 2: フラットレビュープロンプトの構築（1 回限り）

すべてのサブエージェントレビューに送信するプロンプトを正確に記述する。

• MUST: レビュー対象とレビュー観点のみを記述する
• PROHIBIT: 「これは N 回目の試行です」「前回のフィードバック」「過去のイテレーション」「X は修正済み」など、履歴に関する表現を含める
• PROHIBIT: 現在の streak カウントや試行番号を含める
• PROHIBIT: 既知の問題や既知の正常箇所へのヒントを含める
• SHOULD: サブエージェントに構造化された判定（PASS / FAIL + 指摘事項）を返すよう求める

スケルトン例（対象に合わせて調整する）:

"以下の [成果物タイプ] をレビューしてください。正確 / 整形 / 一貫性があるかチェックしてください。判定を返してください: 指摘事項がなければ PASS、あれば FAIL。FAIL の場合、各指摘を箇条書きで列挙してください。"

"[成果物の内容またはパス]"

• MUST: このプロンプトをそのまま保存し、すべてのイテレーションで byte-for-byte 再利用する

Step 3: Findings Log の初期化

すべてのイテレーションにわたる指摘事項のトリアージと修正記録を蓄積する単一の Markdown ファイルを作成する。レビュー対象と同じ場所か .local-agents/ に配置する。

ファイル名規約: <review-target-basename>-findings-log.md

ファイルはヘッダーで始まり append-only で運用する。FAIL イテレーションごとにセクションを追記する。PASS イテレーションは記録しない。

テンプレート:

# Findings Log — <レビュー対象>

<!-- FAIL イテレーションごとに 1 セクション追記 -->

各 FAIL イテレーションで以下の形式のセクションを追記する:

## Attempt #<n>

- **Finding**: <サブエージェントからの指摘文>
  - **Valid?**: yes / no / partial — <妥当性判断の根拠を 1 行で>
  - **Fix**: <何をどこで変更したか（file:line または Edit の要約）>
  - **Verify**: <妥当性をどう確認したか（compile / lint / preview の結果）>

• IF: メインエージェントが指摘を無効（false positive）と判断する; THEN MUST: Valid? フィールドに判断理由を記録し、Fix フィールドに「no fix applied」と記載する。指摘を黙って無視してはならない
• MUST: ログエントリは次のイテレーションに進む前に書き込む（最後にまとめて書かない）

Step 4: ループの実行

streak == N になるまで繰り返す:

1. Step 2 のフラットプロンプトをそのまま使い、新しいサブエージェントを起動する

   • MUST: Agent（サブエージェント）を使用する。メインエージェントのインライン推論で代替しない
   • MUST: model: sonnet を使用する
   • PROHIBIT: 過去のイテレーション、修正、指摘に関するコンテキストを追加する
   • PROHIBIT: イテレーション間でプロンプトの文言を変更する（「今回はもっとよく見て」「X に注目して」などは不可）

2. PASS 基準に基づいて結果を PASS または FAIL に分類する

3. streak を更新する:

   • IF: result == PASS; THEN: streak += 1
   • IF: result == FAIL; THEN: streak = 0（フルリセット。直前に PASS があっても 0 に戻す）

4. IF: FAIL; THEN: サブエージェントが挙げたすべての指摘を修正してからループを続行する

   • MUST: メインエージェントが直接（Write / Edit で）修正する。修正用サブエージェントに委譲しない
   • MUST: 次のレビューの前に成果物が有効な状態であることを再検証する（compile / lint / preview 等）
   • MUST: 各指摘のトリアージと修正を findings log に記録する（Step 3 参照）

5. IF: 結果が malformed（明確な PASS/FAIL 判定なし、サブエージェントのクラッシュ、タイムアウト）; THEN:

   • PASS にも FAIL にもカウントしない。streak を更新しない
   • 報告: attempt #<n>: MALFORMED — 同一フラットプロンプトで再実行
   • ループを続行する（次のイテレーションで同一フラットプロンプトを再実行）

6. 各イテレーション後に進捗を 1 行で報告する:

   • attempt #<n>: <PASS|FAIL> — streak <current>/<N>
   • IF: 非ゼロ streak 後に FAIL; THEN MUST: streak リセットを明示する（例: streak reset 2 → 0）

7. 停止条件: streak == N → 成功を宣言し、総試行回数を報告する

Step 5: 結果の報告

streak == N に達した時点で:

• 総試行回数を報告する
• 最終的な成果物の状態を報告する
• PROHIBIT: N 回目の連続 PASS が確定する前に成功を宣言する

ルールサマリー

• IF: サブエージェントにプロンプトを送信する; THEN MUST: Step 2 で構築した履歴なしの固定プロンプトをそのまま送信する
• IF: 1 回以上の PASS の後にレビューが FAIL する; THEN MUST: streak を 0 にリセットする（1 減算ではない）
• IF: ユーザーがループ中に対象を中断または変更する; THEN MUST: 現在の streak を破棄し、Step 1 からやり直す
• IF: レビューが FAIL する; THEN MUST: 次のイテレーションに進む前に、各指摘のトリアージ・妥当性判断・修正を findings log（Step 3）に記録する
• PROHIBIT: サブエージェントに現在の streak、試行番号、修正内容を伝える
• PROHIBIT: FAIL 時に修正ステップをスキップする。すべての指摘事項は次のレビュー前に対処しなければならない
• PROHIBIT: no-op レビュー（クラッシュ、タイムアウト、malformed 出力）を PASS としてカウントする。同一フラットプロンプトで再実行する

アンチパターン

• 「これはレビュー #3 です。前のレビュアーは X, Y と言いました。確認してください。」→ サブエージェントが過去の指摘にアンカリングし、独立したレビューでなくなる
• 「図の矢印は修正済みです。ラベルに集中してください。」→ リグレッションリスクを隠蔽する。サブエージェントは「修正済み」の箇所をスキップする
• 2 回 PASS + 1 回 FAIL + 1 回 PASS を streak = 1 とカウント → リセットセマンティクスの誤り。FAIL が発生した時点で streak は 0 に戻る
• イテレーション間でプロンプトの文言を微調整する → 各イテレーションは byte-identical でなければならない。そうでなければ streak は同じものを測定していない
• サブエージェントの代わりにメインエージェントがセルフレビューする → 独立性の保証が崩れる。メインエージェントは履歴を知っている
• 最初の PASS で成功を宣言する → 目的は N 回連続であり、1 回の PASS では不十分