error-recovery

エラーからの回復

概要

AI エージェントは行き詰まります。同じアプローチを繰り返し、複雑さを解消するためにさらに複雑さを加え、効果が薄れて久しいにもかかわらず「もう一度だけ試そう」と自分に言い聞かせます。このスキルは、行き詰まりのパターンを事前に検出し、無駄な作業が膨らむ前に回復を強制します。

基本原則： 失敗した試行をすべて記録します。定められたしきい値でエスカレーションします。際限のない再試行は決して許しません。

最優先の指示

NO CONTINUED ATTEMPTS WITHOUT ACKNOWLEDGING FAILURE COUNT

修正を試みる前に、必ず「これは現在の問題に対する N 回目の試行です」と宣言します。N >= 3 の場合、ユーザーの指示なしに続行する権限はありません。

使用するタイミング

次のパターンのいずれかが現れると、このスキルは自動的に有効になります。

• 修正を 2 回以上試した後も、同じエラーメッセージが表示される
• 問題 A の修正によって問題 B が発生する
• 同じ問題について、解決しないままファイルを 3 回以上編集する
• 試行のたびに行数や複雑さが増している
• 2 回以上失敗した後に「もう一つだけ試してみます」と言う
• テストスイートの結果が改善せず、悪化している
• 修正を元に戻し、同じアプローチを少し変えて試す

このスキルは楽観的な見通しより優先されます。 発動した場合、現在失敗している戦略よりも優先されます。

失敗カウンター

問題ごとに内部の失敗カウンターを必ず維持します。

FAILURE LOG
Issue: [description]
Attempt 1: [what you tried] -> [result]
Attempt 2: [what you tried] -> [result]
Attempt 3: [what you tried] -> [result]  <- STOP HERE

ルール：

• 「小さな調整」も含め、修正を試みるたびにカウンターを増やします
• 同じアプローチを少し変えたものも新たな試行として数えます
• 元に戻して再試行する場合も新たな試行として数えます
• カウンターをリセットするのは、問題が解決した場合、またはユーザーが明示的に対象範囲をリセットした場合に限ります

深刻度レベル

Yellow -- 失敗 2 回

• 懸念を明示的に記録します：「[issue] に対する 2 回の試行が失敗しました。」
• 2 回の試行に共通していた点を特定します
• 次の試行では、根本的に異なるアプローチを必ず使います
• 異なるアプローチを特定できない場合は、直ちに Orange にエスカレーションします

Orange -- 失敗 3 回

• 修正の試行をすべて停止します。
• いったん完全に立ち止まり、元のエラーを最初から読み直します
• 初めて目にしたかのように問題を再分析します
• 分かっていること、仮定したこと、未検証のことを列挙します
• これまでの仮定に反する新たな仮説を立てます
• 状況をユーザーに伝えます：「3 回の試行が失敗しました。分析を見直した結果をお伝えします。」

Red -- 失敗 4 回以上

• 停止します。ユーザーの明示的な指示なしに続行してはいけません。
• 誠実に状況を説明します。
  • 試した内容（すべての試行を簡潔に）
  • 各失敗から分かったこと
  • 実際の問題として考えられること
  • 次のステップとして推奨する内容（「解決できない可能性があります」も含む）
• 続行する前にユーザーの入力を待ちます
• ユーザーから続行の指示があった場合は、新しい方針で Yellow にリセットします

エスカレーションのフローチャート

digraph recovery {
  rankdir=TB
  node [shape=box]

  start [label="Fix attempt fails"]
  count [label="Increment failure counter"]
  check [label="How many failures?"]
  yellow [label="YELLOW: Log concern\nTry fundamentally different approach"]
  orange [label="ORANGE: STOP\nRe-analyze from scratch\nPresent revised analysis"]
  red [label="RED: HALT\nPresent honest assessment\nWait for user direction"]
  resolved [label="Issue resolved\nReset counter"]
  user [label="User provides direction\nReset to Yellow"]

  start -> count
  count -> check
  check -> yellow [label="2"]
  check -> orange [label="3"]
  check -> red [label="4+"]
  yellow -> start [label="Next attempt fails"]
  yellow -> resolved [label="Fix works"]
  orange -> start [label="New hypothesis\nattempt fails"]
  orange -> resolved [label="Fix works"]
  red -> user [label="User responds"]
  user -> start [label="New attempt"]
}

回復戦略

修正に失敗した場合は、次の順に適用します。

1. 実際のエラーメッセージを読み直します。 自分なりの解釈ではなく、文字どおりのメッセージを確認します。エラーに答えが含まれていることはよくあります。

2. 根本的に異なるアプローチを試します。 少し変えるだけではいけません。設定を編集していたならコードを試します。パッチを当てていたなら置き換えを試します。追加していたなら削除を試します。

3. 徹底的に単純化します。 問題を再現できる最小のケースに切り分けます。必須でないものをすべて取り除きます。可能な限り単純なバージョンをテストします。

4. 前提を検証します。 値を出力します。型を確認します。編集しているつもりのファイルが、実際に実行されているファイルかを確認します。呼び出されているつもりの関数が、実際に呼び出されているかを確認します。

5. 誠実にエスカレーションします。 ユーザーに「N 通りのアプローチを試しましたが、どれもうまくいきませんでした。分かっていることと、推奨する対応をお伝えします」と伝えます。

6. 最後に正常動作が確認できた状態にロールバックします。 状況を悪化させてしまった場合は、すべての変更を元に戻し、最後に正常に動作していた状態に戻します。そこから新たに始めます。

ブロックすべきアンチパターン

次のパターンはエージェントが行き詰まっていることを示しており、このスキルを必ず有効にしてください。

アンチパターン	代わりにすべきこと
「もう一度だけ試してみます」（3 回以上失敗した後）	停止してください。前回もそう言いました。エスカレーションしてください。
複雑さを解消するために複雑さを追加する	単純化してください。コードを削除してください。変動要素を減らしてください。
エラーメッセージを無視して、手当たり次第に変更を試す	エラーを読んでください。具体的な情報が示されています。
環境のせいにする（「キャッシュの問題に違いない」）	その主張を検証してください。クリーンビルドを実行してください。実際に確認してください。
範囲を絞らず、広げる	システム全体ではなく、失敗する最小のケースに焦点を当ててください。
同じファイルを何度も編集する	一歩引いてください。問題はそのファイルにないかもしれません。
検証せずに「動くはずです」と言う	実行してください。出力を確認してください。期待ではなく、証拠を信頼してください。
コードではなくテストを修正する	テストはおそらく正しいです。テスト対象を修正してください。

認知の罠

正当化	実情
「これは別の問題です」	元の問題を修正している最中に発生したなら、同じ問題です。数に入れてください。
「前回はほぼうまくいきました」	ほぼうまくいった、では不十分です。ニアミスが 2 回続けば、進歩ではなくパターンです。
「アプローチは正しく、少し調整するだけです」	同じアプローチを 3 回調整しても、3 種類の試行にはなりません。
「まずシステム全体を理解する必要があります」	理解すべきなのは失敗している部分です。範囲を広げるのではなく、絞ってください。
「先にリファクタリングしてから修正します」	デバッグ中のリファクタリングは、問題を 2 つに増やします。まず修正してください。
「これはエッジケースです」	完了を妨げるなら、主要なケースです。
「ログをもう 1 つ出せば原因がわかるはずです」	ログを 3 つ出しても役に立たなかったなら、見るべき場所が違います。

ガードレール

次の状況に気づいたら、停止してこのスキルを有効にしてください。

• 1 つの問題に対して同じファイルを 3 回以上編集した
• 修正によって新たな失敗が発生した
• 元の機能よりも、エラーに対処するために多くのコードを書いている
• テストスイートの失敗数が、作業開始時より増えている
• エラーや警告を修正せずに抑制している
• 3 回目以降に「試してみます」と言おうとしている
• 解決策が元の問題より複雑になっている
• 同じエラーに対して、実際に試行を続けて 10 分以上経過している

関連項目

• godmode:fault-diagnosis -- 障害診断で収束しない場合に、エラーリカバリーが有効になります。フェーズ 4 が 3 回以上失敗した場合、このスキルが引き継ぎます。
• godmode:completion-gate -- リカバリー後は、completion-gate を使って修正が実際に維持されていることを確認してください。リカバリー手順の後に、誤って「完了」と判断するのを防ぎます。
• godmode:test-first -- リカバリーには、正確な失敗を再現するテストの作成を含めてください。回帰テストのない修正は未完了です。
• godmode:task-planning -- リカバリーによってタスクの範囲設定が誤っていたとわかった場合は、続行する前にタスク計画に戻って範囲を再設定してください。