agent-introspection-debugging

name	agent-introspection-debugging
description	キャプチャ、診断、抑制されたリカバリ、内省レポートを用いた、AI エージェント障害向けの体系的なセルフデバッグワークフローです。
origin	ECC

Agent Introspection Debugging

このスキルは、エージェント実行が繰り返し失敗する、進捗なくトークンを消費する、同じツールでループする、または意図されたタスクからドリフトしている場合に使用します。

これはワークフロースキルであり、隠れたランタイムではありません。エージェントに対して、人間にエスカレートする前に体系的に自身をデバッグする方法を教えます。

発動タイミング

• ツール呼び出し上限・ループ制限による失敗
• 前進のないリトライの繰り返し
• 出力品質を劣化させ始めるコンテキスト肥大やプロンプトドリフト
• 期待と現実の間の file-system または環境状態の不一致
• 診断とより小さな是正アクションで回復可能な可能性が高いツール障害

スコープ境界

このスキルは以下の目的で発動します:

• 盲目的にリトライする前に障害状態をキャプチャする
• エージェント特有の一般的な障害パターンを診断する
• 抑制されたリカバリアクションを適用する
• 構造化された人間可読のデバッグレポートを生成する

以下の主目的には使用しないでください:

• コード変更後の機能検証。代わりに verification-loop を使用
• より狭い範囲の ECC スキルが既に存在する、フレームワーク固有のデバッグ
• 現在の harness が自動強制できないランタイムの約束

4 フェーズループ

フェーズ 1: 障害キャプチャ

リカバリを試みる前に、障害を正確に記録します。

キャプチャすべき内容:

• エラータイプ、メッセージ、可能な場合はスタックトレース
• 最後の意味のあるツール呼び出しシーケンス
• エージェントが何をしようとしていたか
• 現在のコンテキスト圧: 繰り返されるプロンプト、過大なログの貼り付け、重複したプラン、または暴走するノート
• 現在の環境前提: cwd、ブランチ、関連するサービス状態、期待されるファイル

最小キャプチャテンプレート:

## Failure Capture
- Session / task:
- Goal in progress:
- Error:
- Last successful step:
- Last failed tool / command:
- Repeated pattern seen:
- Environment assumptions to verify:

フェーズ 2: 根本原因診断

何かを変更する前に、障害を既知のパターンと一致させます。

パターン	想定原因	確認方法
ツール呼び出し上限 / 同一コマンドの繰り返し	ループまたは終了なしの observer パス	直近 N 件のツール呼び出しを調べて繰り返しを確認
コンテキストオーバーフロー / 推論の劣化	上限のないノート、プラン重複、過大なログ	最近のコンテキストで重複と低シグナルの塊を確認
ECONNREFUSED / タイムアウト	サービス停止中または誤ったポート	サービスヘルス、URL、ポート前提を検証
429 / クォータ枯渇	リトライストームまたはバックオフ欠如	繰り返し呼び出しを数え、リトライ間隔を調査
書き込み後のファイル欠如 / 古い diff	レース、誤った cwd、またはブランチドリフト	パス、cwd、git status、実際のファイル存在を再確認
「修正」後もテスト失敗	誤った仮説	正確な失敗テストを分離し、バグを再導出

診断質問:

• これはロジック障害、状態障害、環境障害、またはポリシー障害か?
• エージェントは本来の目的を見失い、誤ったサブタスクを最適化し始めていないか?
• 障害は決定論的か、一時的か?
• 診断を検証する最小の可逆アクションは何か?

フェーズ 3: 抑制されたリカバリ

診断面を変える最小のアクションでリカバリします。

安全なリカバリアクション:

• 繰り返しのリトライを停止し、仮説を再表明する
• 低シグナルのコンテキストをトリミングし、アクティブなゴール、ブロッカー、証拠のみを保持する
• 実際の filesystem / ブランチ / プロセス状態を再確認する
• タスクを 1 つの失敗コマンド、1 ファイル、または 1 テストに絞る
• 推測的推論から直接観察に切り替える
• 障害が高リスクまたは外部的にブロックされている場合、人間にエスカレートする

実際に現在の環境で本物のツールを通じて行っているのでない限り、「エージェント状態をリセット」や「harness 設定を更新」といった、サポートされていない自動修復アクションを主張しないでください。

抑制されたリカバリチェックリスト:

## Recovery Action
- Diagnosis chosen:
- Smallest action taken:
- Why this is safe:
- What evidence would prove the fix worked:

フェーズ 4: 内省レポート

次のエージェントまたは人間にリカバリが理解できるようレポートで締めくくります。

## Agent Self-Debug Report
- Session / task:
- Failure:
- Root cause:
- Recovery action:
- Result: success | partial | blocked
- Token / time burn risk:
- Follow-up needed:
- Preventive change to encode later:

リカバリヒューリスティクス

以下の介入を順に優先します:

1. 本当の目的を 1 文で再表明する。
2. メモリを信頼するのではなく、ワールドステートを検証する。
3. 失敗スコープを縮小する。
4. 1 つの判別チェックを実行する。
5. その後でのみリトライする。

悪いパターン:

• 同じアクションをわずかに異なる言い回しで 3 回リトライする

良いパターン:

• 障害をキャプチャする
• パターンを分類する
• 1 つの直接的なチェックを実行する
• チェックが支持する場合にのみプランを変更する

ECC との統合

• コード変更後は verification-loop を使用してリカバリします。
• 障害パターンを直感や後のスキルにする価値がある場合は continuous-learning-v2 を使用します。
• 問題が技術的失敗ではなく決定の曖昧さである場合は council を使用します。
• 障害がローカル状態の競合やリポジトリドリフトに由来する場合は workspace-surface-audit を使用します。

出力基準

このスキルが有効な場合、「修正しました」だけで終えないでください。

常に以下を提供します:

• 障害パターン
• 根本原因仮説
• リカバリアクション
• 状況が改善されたか、まだブロックされているかの証拠