fable-recover

Fable Recover

失敗する仮説に変更を費やすのはやめましょう。コードを再び変更する前に、因果関係への確信を築き直します。

ミッション

リカバリーが必要になるのは、エージェントが最も無駄にコストをかけ、非合理的になりやすい場面です。同じタスクが複数回失敗したとき、出力が期待と矛盾するとき、または編集が何の効果もないように見えるときです。

目標は「何か別のことを試す」ことではありません。以前の試みが失敗した理由を説明し、競合する原因を反証したうえで、新たな証拠に基づく修正を1つ行うことです。

有効化する条件

• 実装を実質的に同じ形で2回試みた後も、同じコマンド／テスト／動作が失敗する。
• 既知のソース変更が反映されず、出力が古い、または影響を受けていないように見える。
• テストと実行時の挙動が一致しない。
• 重要な前提と証拠が矛盾する。
• 失敗が交互に起きる、またはタイミング／環境に依存する。
• エージェントが、新たな診断情報なしにコマンド／パッチを繰り返そうとしている。

有効化しない条件

• 現在の編集によって、単純な構文エラー／型エラーが初めて発生した。
• アーキテクチャが単に不明なだけで、失敗が繰り返されていない（fable-discover）。
• TDDで想定されるREDが正しく確認されている。
• 範囲の狭いレビュー指摘に対して、明確で限定的な修正方法がすでにある。

失敗の分類

コードではなく、まず証拠を分類します。

分類	典型的な兆候	最初の調査
テストハーネス	アサーションに到達しない、フィクスチャ／モック／セットアップのエラー	テストパスとフィクスチャを確認する
環境	ローカル／CI／OS／環境に固有	バージョン、環境変数、作業ディレクトリ、権限
成果物／キャッシュ	ソース変更が反映されない	エントリーポイント、ビルドのタイムスタンプ、キャッシュ、dist
実行経路	編集したコードが実行されない	トレース／計装／登録
依存関係／バージョン	想定外のAPI／実行時セマンティクス	ロックファイル、解決されたバージョン、公式情報
データ／状態	一部のフィクスチャ／アカウント／注文だけで失敗する	最小限の失敗状態、永続化の境界
並行性／タイミング	断続的に発生する／順序に依存する	決定論的な同期、共有状態
製品ロジック	テストハーネス／実行経路が確認済みで、アサーションが一貫して誤る	アルゴリズム／分岐を切り分ける
不変条件／設計	局所的な修正で別の箇所に失敗が移る	コンポーネント間のどのルールに違反しているかを特定する

より低コストな外部要因を反証するまでは、製品ロジックに飛びつかないでください。

リカバリープロトコル

ステージ1 — 変更を凍結する

診断が変わるまで、新たな本番コードの編集は行いません。失敗状態を保ち、正確な証拠を収集します。

次の項目を記録します。

• コマンド／操作；
• 正確なエラー／出力；
• ワークスペース／コミット／変更の世代；
• すでに行った試みと、その違い；
• 期待される観察結果。

ステージ2 — 最小限で再現する

確実に再現できる最小の手順を見つけます。失敗が不安定な場合は、修正を試す前にシード値／順序／時間／環境を記録し、決定性の確保に取り組みます。

ステージ3 — 仮説のキューを作る

次の点を基準に、もっともらしい原因を2～5個挙げ、順位を付けます。

• 観察されたすべての証拠を説明できるか；
• 最近の変更を踏まえた発生確率；
• 反証にかかるコスト／安全性。

それぞれの仮説は、他の仮説と区別できる観察結果を予測する必要があります。

悪い例：「キャッシュかもしれない。」

良い例：「CLIは古い dist/cli.js を実行している。これが正しければ、ソースのタイムスタンプはdistより新しく、ソースを直接実行すると新しい動作が確認できる。」

ステージ4 — 原因特定の段階を順に確認する

最も低コストで原因を切り分けられる調査から始めます。

1. テストハーネス — テスト／調査手順は、現実的な入力で意図したアサーション／経路に到達しているか？
2. 環境／成果物 — ブランチ、作業ディレクトリ、環境、バージョン、ビルド、キャッシュ、プロセスは正しいか？
3. 実行経路 — 編集したコードは実際に実行されているか？どの実装が登録されているか？
4. データ／依存関係 — 入力／バージョン／状態は前提と異なっていないか？
5. 製品ロジック — 上記を確認したうえで、誤った分岐／アルゴリズムを切り分ける。
6. 不変条件／設計 — 局所的なロジックは個別には妥当に見えるのにシステム全体が誤ったままなら、違反しているシステムの契約を特定する。

この段階分けは指針であり、形式的な手順ではありません。既存の証拠で確認できている段階は飛ばしてかまいません。

ステージ 5 — 観察が不十分な場合は計測するか、二分探索する

対象を絞った一時的な診断、二分探索、変数を 1 つ切り替える方法、または正常な状態と異常な状態の比較を行います。

結果を解釈できるよう、診断の観点は一度に 1 つだけ変更します。

ステージ 6 — 推測を積み重ねず、仮説を反証する

各プローブの後に、次のいずれかを行います。

• 仮説を棄却する。
• 仮説を強める。
• または、仮説の検証順を見直す。

反証された説明を「まだ関係しているかもしれない」として残してはいけません。

ステージ 7 — 修正後の診断をまとめる

妥当な診断では、次のことを説明します。

• 観察された障害がなぜ起きたのか。
• これまでの試みでなぜ修正できなかったのか。
• どの証拠によって他の原因と区別できるのか。
• 最小限の修正で何を変えれば結果が変わるのか。

ステージ 8 — 範囲を限定した修正を 1 つ行う

修正を 1 つ、その効果を証明するために期待される結果を 1 つ添えて、fable-execute または fable-tdd に戻します。診断によってアーキテクチャの不確実性が明らかになった場合は、代わりに plan/discover に回します。

判断ルール

• 名前を指定した環境変数または状態変数が変わった場合、あるいは再実行による非決定性の測定を明示的に行う場合を除き、変更のない失敗したコマンドを繰り返してはいけません。
• 証拠を記録する前に、反射的にキャッシュやビルド成果物を削除してはいけません。破壊的なクリーンアップによって、古さを証明する手掛かりが消えることがあります。
• ソースの変更が実行時の挙動に反映されない場合は、ロジックを再度編集する前に、実行されている成果物やパスを証明します。
• CI でのみ失敗する場合は、まず環境、バージョン、並列実行を比較します。CI は「ランダム」だと決めつけてはいけません。
• 特定のデータで失敗する場合は、大規模なリファクタリングの前に、失敗するデータや状態を最小化します。
• 依存関係やバージョンに関する仮説が浮上した場合は、外部の意味的な検証を fable-research に回します。
• ローカルのパッチによって障害がコンポーネント間を移動する場合は、共通の不変条件や設計上の問題を疑い、fable-plan に戻ります。
• 同様の修正の失敗は、失敗の連続として数えます。表面的な構文変更をしても、診断の責任はリセットされません。

不変条件

• 修正後の診断が得られるまでは、復旧作業は診断のみとし、読み取り専用で行います。
• 新しい各プローブは、仮説を見分けるために選びます。
• 反証された仮説は取り除きます。
• 診断用の計測は一時的なものとし、修正後に削除します。
• 最終的な修正は範囲を限定し、予測した観察可能な結果に結び付けます。

復旧プロセス自体の失敗分類

やみくもなクリーンアップ

キャッシュやビルドをリセットして問題が消えても、根本原因は不明です。因果関係の証拠が得られない限り、未解決として記録します。

仮説の乱立

識別用のプローブがないまま、可能性の長いリストができています。優先順位を付け、最も低コストで見分けられるものをテストします。

診断中の変更

不確実なままエージェントが製品を編集し、失敗状態が無効になります。安全であれば診断時のベースラインに戻して復元し、証拠の収集を再開します。

確証バイアス

最初の仮説を支持するプローブだけが実行されています。最有力の仮説を反証するプローブを少なくとも 1 つ追加します。

最小化されていない再現

大規模なテストスイートやシステムにより、交絡要因が多くなっています。結果を解釈する前に、より小さな経路に切り分けます。

アンチパターン

• 同じ因果関係の仮説に基づく 3 回目、4 回目のパッチ。
• 変更前後の証拠を記録せずに「キャッシュをクリアして確認する」こと。
• 不安定なコマンドを成功するまで再実行すること。
• 環境を比較せずに環境のせいにすること。
• あらゆる場所に広範なログを追加すること。
• 診断変数を一度に複数変更すること。
• 反証された前提を残すこと。
• 過去の試みが失敗した理由を説明できないまま、症状だけを解消すること。

復旧パケット

Failure/reproduction:
Attempts already made:
Hypothesis queue:
Probe → observation → hypothesis effect:
Revised diagnosis:
Why prior attempts failed:
Bounded repair:
Expected proof after repair:
Residual uncertainty:
Next Skill:

完了条件

復旧が完了するのは、次の条件を満たした場合のみです。

• 十分に信頼できる再現方法があるか、非決定性が明確に特徴付けられている。
• 有力な別の原因が、証拠によって反証されている。
• 診断が、失敗した前提や試みから実質的に異なる。
• 提案する修正の範囲が限定され、具体的に変化する観察結果を予測している。
• やみくもな再試行をせずに実行を再開できる。

段階的なリソース

• 詳細ガイド：references/diagnostic-falsification-playbook.md
• 既存の手順：references/attribution-ladder.md
• 例：examples/recovering-stale-test-cache.md