affaan-m/agent-introspection-debugging

エージェント内省デバッグ

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

これはワークフロースキルであり、隠れたランタイムではありません。エージェントが人間にエスカレーションする前に体系的に自己デバッグするよう教えます。

起動タイミング

• ツール呼び出しの最大数 / ループ制限の失敗
• 前進なしの繰り返しリトライ
• 出力品質の低下を招くコンテキストの増大またはプロンプトのドリフト
• 期待と現実の間でのファイルシステムや環境状態の不一致
• 診断とより小さな修正アクションで回復可能なツールの失敗

スコープ境界

このスキルを起動するのは以下の場合：

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

このスキルを主なソースとして使用しない場合：

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

四フェーズループ

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

回復を試みる前に、障害を正確に記録します。

キャプチャ内容：

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

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

## 障害キャプチャ
- セッション / タスク:
- 進行中の目標:
- エラー:
- 最後に成功したステップ:
- 最後に失敗したツール / コマンド:
- 観察された繰り返しパターン:
- 検証すべき環境の前提:

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

何も変更する前に、障害を既知のパターンに照合します。

| パターン | 考えられる原因 | チェック | | --- | --- | --- | | ツール呼び出しの最大数 / 同じコマンドの繰り返し | ループまたは出口なしのオブザーバーパス | 最後の N 回のツール呼び出しを繰り返しについて検査する | | コンテキストオーバーフロー / 推論の低下 | 無制限のノート、繰り返される計画、過大なログ | 最近のコンテキストを重複と低シグナルのバルクについて検査する | | ECONNREFUSED / タイムアウト | サービスが利用不可または間違ったポート | サービスの健全性、URL、ポートの前提を確認する | | 429 / クォータ枯渇 | リトライストームまたはバックオフなし | 繰り返し呼び出しを数え、リトライ間隔を検査する | | 書き込み後にファイルが見つからない / 古い差分 | レース、間違った cwd、またはブランチドリフト | パス、cwd、git ステータス、実際のファイル存在を再確認する | | 「修正」後もテストが失敗し続ける | 間違った仮説 | 失敗している正確なテストを分離し、バグを再導出する |

診断の質問：

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

フェーズ 3: 封じ込め回復

診断の表面を変える最小のアクションで回復します。

安全な回復アクション：

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

現在の環境の実際のツールを通じて実際にそれらを行っていない限り、「エージェント状態をリセット」または「ハーネス設定を更新」のような自動回復アクションを主張しないこと。

封じ込め回復チェックリスト：

## 回復アクション
- 選択した診断:
- 取った最小アクション:
- なぜこれが安全か:
- 修正が機能したことを証明するエビデンスは何か:

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

次のエージェントや人間が回復を理解できるレポートで終了します。

## エージェント自己デバッグレポート
- セッション / タスク:
- 障害:
- 根本原因:
- 回復アクション:
- 結果: 成功 | 部分的 | ブロック中
- トークン / 時間の消費リスク:
- 必要なフォローアップ:
- 後でエンコードすべき予防的変更:

回復ヒューリスティクス

この順序で介入を優先する：

1. 実際の目標を一文で再述べる。
2. メモリを信頼するのではなく世界の状態を確認する。
3. 失敗しているスコープを縮小する。
4. 1 つの識別チェックを実行する。
5. その後にのみリトライする。

悪いパターン：

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

良いパターン：

• 障害をキャプチャする
• パターンを分類する
• 1 つの直接チェックを実行する
• チェックがサポートする場合にのみ計画を変更する

ECC との統合

• コードが変更された場合、回復後に verification-loop を使用する。
• 障害パターンが本能や将来のスキルに変える価値がある場合は continuous-learning-v2 を使用する。
• 問題が技術的な失敗ではなく決定の曖昧さである場合は council を使用する。
• 障害が競合するローカル状態やリポジトリのドリフトから来た場合は workspace-surface-audit を使用する。

出力標準

このスキルがアクティブな場合、「修正しました」だけで終わらないこと。

常に提供する：

• 障害パターン
• 根本原因の仮説
• 回復アクション
• 状況が改善されたまたはまだブロックされているエビデンス