agent-introspection-debugging

代理內省除錯

當代理執行持續失敗、消耗 token 卻無進展、重複使用相同工具、或偏離預期任務時，使用此技能。

這是一個工作流程技能，而非隱藏執行環境。它教導代理在升級給人類之前，系統性地自我除錯。

何時啟用

• 達到最大工具呼叫/迴圈限制失敗
• 重複重試但無進展
• 上下文增長或提示偏移導致輸出品質下降
• 檔案系統或環境狀態與預期不符
• 工具失敗但可透過診斷與小型修正動作復原

範圍邊界

啟用此技能用於：

• 在盲目重試前捕捉失敗狀態
• 診斷常見的代理特定失敗模式
• 執行受控復原動作
• 產生結構化、人類可讀的除錯報告

請勿將此技能作為以下情況的主要來源：

• 程式碼變更後的功能驗證；請使用 verification-loop
• 框架特定的除錯，當已有更狹義的 ECC 技能時
• 目前執行環境無法自動強制的執行期承諾

四階段迴圈

階段 1：失敗捕捉

在嘗試復原之前，精確記錄失敗。

捕捉：

• 錯誤類型、訊息與堆疊追蹤（若可用）
• 最後有意義的工具呼叫序列
• 代理當時嘗試做的事
• 當前上下文壓力：重複提示、過大的貼上日誌、重複的計畫、或失控的筆記
• 當前環境假設：工作目錄、分支、相關服務狀態、預期檔案

最小捕捉模板：

## 失敗捕捉
- 工作階段/任務：
- 進行中的目標：
- 錯誤：
- 最後成功步驟：
- 最後失敗工具/指令：
- 觀察到的重複模式：
- 需驗證的環境假設：

階段 2：根本原因診斷

在變更任何事物之前，將失敗比對到已知模式。

模式	可能原因	檢查方式
達到最大工具呼叫/重複相同指令	迴圈或無退出觀察路徑	檢查最近 N 次工具呼叫是否重複
上下文溢位/推理能力下降	無限制的筆記、重複計畫、過大日誌	檢查近期上下文是否有重複與低訊號的大量內容
ECONNREFUSED / 逾時	服務不可用或連接埠錯誤	驗證服務健康狀態、URL 與連接埠假設
429 / 配額耗盡	重試風暴或缺少退避	計算重複呼叫次數並檢查重試間隔
寫入後檔案遺失/差異過時	競爭條件、錯誤工作目錄或分支偏移	重新檢查路徑、工作目錄、git 狀態與實際檔案是否存在
修正後測試仍失敗	錯誤假設	隔離確切失敗的測試並重新推斷錯誤

診斷問題：

• 這是邏輯失敗、狀態失敗、環境失敗還是策略失敗？
• 代理是否失去真正目標，開始最佳化錯誤的子任務？
• 失敗是確定性還是暫時性？
• 哪個最小的可逆動作可以驗證診斷？

階段 3：受控復原

以改變診斷表面的最小動作進行復原。

安全復原動作：

• 停止重複重試，重新陳述假設
• 修剪低訊號上下文，僅保留當前目標、阻礙與證據
• 重新檢查實際檔案系統/分支/程序狀態
• 將任務縮小到一個失敗指令、一個檔案或一個測試
• 從推測推理轉為直接觀察
• 當失敗是高風險或外部阻擋時，升級給人類

除非你確實透過當前環境中的真實工具執行，否則不要聲稱不支援的自動修復動作，例如「重置代理狀態」或「更新執行環境設定」。

受控復原檢查清單：

## 復原動作
- 選擇的診斷：
- 採取的最小動作：
- 為何安全：
- 哪些證據可證明修復有效：

階段 4：內省報告

以一份讓下一個代理或人類能理解的報告結束。

## 代理自我除錯報告
- 工作階段/任務：
- 失敗：
- 根本原因：
- 復原動作：
- 結果：成功 | 部分成功 | 受阻
- Token/時間耗損風險：
- 需要後續處理：
- 後續應編碼的預防性變更：

復原啟發式

優先採用以下干預措施（按順序）：

1. 用一句話重新陳述真正目標。
2. 驗證世界狀態，而非信任記憶。
3. 縮小失敗範圍。
4. 執行一個區別性檢查。
5. 然後才重試。

不良模式：

• 用稍微不同的措辭重複相同動作三次

良好模式：

• 捕捉失敗
• 分類模式
• 執行一個直接檢查
• 僅在檢查支持時才變更計畫

與 ECC 整合

• 若程式碼有變更，復原後使用 verification-loop。
• 當失敗模式值得轉化為直覺或後續技能時，使用 continuous-learning-v2。
• 當問題不是技術失敗而是決策模糊時，使用 council。
• 若失敗來自衝突的本機狀態或儲存庫偏移，使用 workspace-surface-audit。

輸出標準

當此技能啟用時，不要僅以「我修好了」結束。

務必提供：

• 失敗模式
• 根本原因假設
• 復原動作
• 證明情況已改善或仍受阻的證據