Agent Introspection

Agent Introspection 🔍

「同じ tool を 3 回叩く前に、世界の状態を確認せよ。」

Core principle: agent が repeated failure に遭遇したとき、 blind retry は token を消費するだけで前進しない。 失敗を capture → diagnose → contained recovery の構造で扱い、推測ではなく観察で動く。

The Iron Rule

3 回失敗したら、 retry を止めて diagnose せよ

「もう 1 回試せば動くかも」は agent failure の anti-pattern 1 番。

いつ使うか

AI agent (Claude Code session / VP Stand actor / VP worker lane / 自作 LLM agent) が次のような症状を見せたとき:

• Max tool call / loop limit で停止
• 同じ tool / cmd を 繰り返し呼ぶのに前進しない
• context 肥大で reasoning quality が劣化 (drift)
• file system / 環境状態と expectation の mismatch
• tool failure が連続するが diagnosis 次第で recoverable に見える

いつ使わないか

Scope Boundary

activate 対象:

• 失敗 state の正確な capture
• 既知 failure pattern への match
• contained recovery action の適用
• 構造化された debug report 出力

activate しない:

• 機能検証 (verification の領域)
• 言語/framework 特化 debug (それぞれの skill が存在するならそちらを優先)
• harness 自体が enforce できない runtime promise

4 フェーズ

Capture → Diagnose → Contain → Report

番号でなく名前で参照する。

📸 Capture（失敗 state の記録）

retry 前に正確に失敗を記録する。 blind retry より先に必ず capture。

記録項目

• error type / message / stack trace (取得可能なら)
• 直近の意味のある tool call 列
• agent が達成しようとしていた goal
• context pressure: prompt 重複、 oversize log paste、 plan 重複、 暴走 note
• environment 前提: cwd、 branch、 service state、 期待 file 群

最小 capture テンプレート

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

🔬 Diagnose（root cause の識別）

何かを変える前に、 failure を既知 pattern に match する。

Pattern table (基本)

Diagnosis 質問

• type 判定: logic failure / state failure / environment failure / policy failure のどれ?
• drift 判定: agent は real objective を見失って sub-task を最適化していないか?
• reproducibility: deterministic か transient か?
• smallest reversible action: diagnosis を validate する最小 action は?

🔧 Contain（最小 action での recovery）

diagnosis surface を変える最小 actionを取る。 recovery 自体が cascade を引き起こさないように。

安全 recovery action

• 反復 retry を止め、仮説を restate
• 低 signal context を trim、 active goal + blocker + evidence のみ残す
• 実 file system / branch / process state を 再観測
• task scope を 1 失敗 cmd / 1 file / 1 test に絞る
• speculative reasoning から direct observation に切替
• 高 risk / 外部 blocker なら human escalate

重要: 「reset agent state」「update harness config」のような harness が実際 enforce できない action を約束するな。 actual tool で実行できるものだけを claim せよ。

Contained recovery checklist

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

📋 Report（introspection report）

次の agent / human が読んで動ける形で報告する。 「I fixed it」だけは不十分。

## 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:

Recovery Heuristics（優先順）

1. real objective を 1 sentence で restate する
2. memory ではなく world state を verify する
3. failing scope を shrink する
4. 1 つの discriminating check を実行する
5. それから retry する

creo-memories 連携

agent failure pattern は 再利用可能な instinct になりやすい。 memory に積極的に記録:

学びの形:

• 「context overflow 検出 → trim → recover」が 3 回起きたら、自動 trim hook を harness に追加検討
• 「同 cmd 反復」が頻発する agent → action space 整理 (agent-harness 参照)

chronista 文脈での適用例

例 1: worker autonomous mode の drift

Worker が autonomous で走っていて、同じ tool を反復し始めた:

1. Capture: 直近 10 tool call を log、 goal restate、 wire_send で lead に状態通知
2. Diagnose: pattern table から「Max tool calls / 同 cmd 反復」 → loop or 出口なし
3. Contain: tool reps を止め、wire_send で lead に「迷ってる、 confirmation 欲しい」 (autonomous の safety valve)
4. Report: 何が trigger だったか、 next session で予防可能か

例 2: Stand actor の event loop drift

VP の PP Stand actor が event を処理せず idle 化:

1. Capture: causation tree で last successful event → idle までの timeline、 inbox の queue 長
2. Diagnose: subscribe topic mismatch? Mailbox 失効?
3. Contain: actor を re-register、 missed event は tail で再 inject
4. Report: failure pattern を memory pin、 D11-G (HP Headless) の参考に

例 3: Long session での context overflow

session が長くなり、 reasoning quality が落ちた感覚があるとき:

1. Capture: 現 context size 推定 (skill list / history / MCP server で何 token 食ってるか)
2. Diagnose: pattern table から「Context overflow / reasoning 劣化」
3. Contain: 不要 plugin disable で skill list 軽減、 strategic compact 提案
4. Report: memory pin (plugin disable 判断を memory 化)

NG パターン

他スキルとの住み分け

発火の目安

• agent / subagent が repeated failure
• 「もう 1 回 retry してみよう」を 2 回以上思った
• token 消費が前進と釣り合わない
• agent が drift して original goal を見失っている感覚
• VP worker lane / VP Stand actor の loop / idle / stuck

逆に発火しないケース:

• 1 回限りの transient error (retry で resolve、 pattern なし)
• コード/build/test failure (systematic-debugging 領域)
• 設計判断の迷い (council 領域)

アンチパターン

Anti-pattern: Blind retry storm

• 症状: 同 cmd を wording 変えて 3 回以上呼ぶ
• 問題: token 消費だけ、 diagnosis surface 変化なし
• 対策: MAX 3 で停止、 capture → diagnose

Anti-pattern: Phantom recovery action

• 症状: 「agent state を reset した」「config を update した」と claim、 実 tool 不在
• 問題: agent が嘘をつき、 後続が信用できない
• 対策: actual tool で実行できる action のみ claim

Anti-pattern: Capture skip

• 症状: 失敗してすぐ recovery 開始
• 問題: root cause 不明のまま、 same failure 再発
• 対策: Capture template を埋めてから次に進む

Anti-pattern: Report 省略

• 症状: 「I fixed it」だけで session を進める
• 問題: 同 failure が次回再発、 instinct 化しない
• 対策: Report template + memory pin

クイックリファレンス

参考

• 元 skill: ECC agent-introspection-debugging (Everything Claude Code)
• 関連 skill: systematic-debugging (コード/システムバグ用、 領域が異なる)
• 姉妹スキル: agent-harness, council, santa-method, verification

Source: chronista-club/claude-plugin-chronista-style — distributed by TomeVault.