| name | agent-introspection |
| description | AI agent 自身の failure (loop / drift / max tool call / 環境ズレ) に対する構造化 self-debug。 capture → diagnose → contained recovery → introspection report の 4 phase で、 retry blind を防ぎ human escalation の前に agent が自己修正する。 Use when this capability is needed. |
| metadata | {"author":"chronista-club"} |
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 に見える
いつ使わないか
| ❌ agent-introspection を使うな | ✅ 代わりに |
|---|
| コード/システムのバグ調査 (test failure / production bug) | systematic-debugging |
| 完了前 deterministic 検証 (build/lint/test) | verification |
| code 変更後の機能検証 | verification |
| 設計判断の合議 | council |
| output の品質検証 | santa-method |
| 完全に runtime 制御不可な領域 (harness 自体の bug) | human escalation |
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 (基本)
| Pattern | 推定 root cause | check |
|---|
| Max tool calls / 同 cmd 反復 | loop / 出口がない observer path | 直近 N 個の tool call を inspect |
| Context overflow / reasoning 劣化 | 無制限 note、 plan 重複、 oversize log | recent context の冗長性を確認 |
ECONNREFUSED / timeout | service 不在 or 不正 port | service health / URL / port を確認 |
429 / quota | retry storm or backoff 欠落 | call 頻度と spacing 確認 |
| 書き込み後 file 不在 / stale diff | race / 不正 cwd / branch drift | path / cwd / git status / 実 file 確認 |
| 修正後も test 失敗 | 仮説が wrong | 失敗 test 1 つに絞り bug 再導出 |
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（優先順）
- real objective を 1 sentence で restate する
- memory ではなく world state を verify する
- failing scope を shrink する
- 1 つの discriminating check を実行する
- それから retry する
| ❌ 悪い pattern | ✅ 良い pattern |
|---|
| 同 action を 3 回 wording だけ変えて retry | capture → classify → 1 direct check → check の結果で plan 変更 |
| 失敗を黙って context に積む | capture を Report で永続化 |
| diagnose なしで retry storm | MAX 3 で escalate |
creo-memories 連携
agent failure pattern は 再利用可能な instinct になりやすい。 memory に積極的に記録:
| 状況 | 記録方法 |
|---|
| 新しい failure pattern | category: learning, tag: [agent-failure, pattern-name] |
| 既知 pattern の再発 | 既存 memory に extends で reply / annotation |
| harness 改善のトリガー | category: design-decision, tag: [harness-evolution, agent-introspection] |
| 緊急 escalation | category: incident, tag: [urgent, agent-stuck] |
学びの形:
- 「context overflow 検出 → trim → recover」が 3 回起きたら、自動 trim hook を harness に追加検討
- 「同 cmd 反復」が頻発する agent → action space 整理 (
agent-harness 参照)
chronista 文脈での適用例
例 1: worker autonomous mode の drift
Worker が autonomous で走っていて、同じ tool を反復し始めた:
- Capture: 直近 10 tool call を log、 goal restate、 wire_send で lead に状態通知
- Diagnose: pattern table から「Max tool calls / 同 cmd 反復」 → loop or 出口なし
- Contain: tool reps を止め、
wire_send で lead に「迷ってる、 confirmation 欲しい」 (autonomous の safety valve)
- Report: 何が trigger だったか、 next session で予防可能か
例 2: Stand actor の event loop drift
VP の PP Stand actor が event を処理せず idle 化:
- Capture: causation tree で last successful event → idle までの timeline、 inbox の queue 長
- Diagnose: subscribe topic mismatch? Mailbox 失効?
- Contain: actor を re-register、 missed event は tail で再 inject
- Report: failure pattern を memory pin、 D11-G (HP Headless) の参考に
例 3: Long session での context overflow
session が長くなり、 reasoning quality が落ちた感覚があるとき:
- Capture: 現 context size 推定 (skill list / history / MCP server で何 token 食ってるか)
- Diagnose: pattern table から「Context overflow / reasoning 劣化」
- Contain: 不要 plugin disable で skill list 軽減、 strategic compact 提案
- Report: memory pin (plugin disable 判断を memory 化)
NG パターン
| ❌ 悪い | ✅ 良い |
|---|
| 失敗してすぐ blind retry | capture → diagnose → contain |
| diagnose なしで「reset agent state」claim | actual tool で実行できる action のみ |
| Report skip して「I fixed it」 | 必ず failure pattern + root cause + recovery + evidence |
| 同 reviewer / agent で fix loop | escalate to human (or fresh agent) |
| failure pattern を memory に残さない | learning category で pin、 instinct 化 |
| systematic-debugging と混同 | コードバグは systematic-debugging、 agent failure は agent-introspection |
他スキルとの住み分け
| スキル | 役割 | agent-introspection との関係 |
|---|
systematic-debugging | コード/システムバグの根本原因調査 | 領域が異なる: agent-introspection = agent 自身の failure、 systematic-debugging = code/system のバグ |
agent-harness | harness 設計 | 補完: harness で予防、 introspection で検出 |
verification | 完了前 deterministic checks | verification は build/test、 introspection は agent 内部 |
council | 設計判断 | introspection の result を council にかける流れもある |
santa-method | output 検証 | santa は output、 introspection は agent process 自身 |
route | path 選択 | route で plot した path が走らなかったとき introspection |
発火の目安
- 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
クイックリファレンス
| Phase | 主な活動 | 完了条件 |
|---|
| Capture | 失敗 state を template に埋める | what / where / why が記述された |
| Diagnose | pattern table と match | root cause hypothesis 確立 |
| Contain | 最小 action で recovery | evidence で fix 確認 or escalate |
| Report | self-debug report 出力 | next agent / human が読んで動ける |
参考
- 元 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.
