Agent Introspection Debugging

Debug agent behavior through four-stage self-diagnosis loop �� capture, diagnose, recover, report. Use when the agent needs structured self-debugging, error recovery, or behavioral analysis.

Agent 自调试工作流。在盲目重试之前，先系统化地捕获、诊断、恢复和报告�?

触发条件

• 工具调用达到上限 / 循环限制
• 反复重试但无进展
• 上下文膨胀导致推理质量下降
• 文件系统/环境状态与预期不符
• 工具失败但可能通过诊断恢复

不用�?

• 代码变更后的功能验证 �?�?Backpressure 门控
• 框架特定调试 �?用语言专属 reviewer
• 运行�?Promise 问题 �?�?hook-engine

四阶段循�?

Phase 1: Failure Capture（故障捕获）

在尝试恢复之前，精确记录失败状态�? 捕获内容�?- 错误类型、消息、堆栈（如有�?- 最后有意义的工具调用序�?- Agent 试图做什�?- 当前上下文压力：重复提示、过大日志、重复计�?- 当前环境假设：cwd、branch、服务状态、预期文�? **最小捕获模�?*�?

markdown

## Failure Capture
- Session / task: [会话/任务标识]
- Goal in progress: [当前目标]
- Error: [错误信息]
- Last successful step: [最后成功步骤]
- Last failed tool / command: [最后失败的工具/命令]
- Repeated pattern seen: [观察到的重复模式]
- Environment assumptions to verify: [需要验证的环境假设]

Phase 2: Root-Cause Diagnosis（根因诊断）

在修改任何东西之前，先匹配已知模式�?

模式	可能原因	检查方�?
最大工具调�?/ 重复相同命令	循环或无退出路�?	检查最�?N 次工具调用是否重�?
上下文溢�?/ 推理降级	无界笔记、重复计划、过大日�?	检查近期上下文是否有重复和低信号内�?
连接拒绝 / 超时	服务不可用或端口错误	验证服务健康、URL、端口假�?
429 / 配额耗尽	重试风暴或缺少退�?	计算重复调用次数和重试间�?
写入后文件丢�?/ diff 过期	竞态、错�?cwd、分支漂�?	重新检查路径、cwd、git status
修复后测试仍失败	假设错误	隔离确切的失败测试，重新推导 bug

诊断问题�?- 这是逻辑失败、状态失败、环境失败还是策略失败？

• Agent 是否失去了真实目标，开始优化错误的子任务？
• 失败是确定性的还是瞬态的�?- 什么是最小的可逆操作来验证诊断�?

Phase 3: Contained Recovery（受控恢复）

用最小的操作改变诊断表面�? 安全恢复操作�?- 停止重复重试，重述假�?- 裁剪低信号上下文，只保留活动目标、阻塞点和证�?- 重新检查实际的文件系统/分支/进程状�?- 将任务缩小到一个失败命令、一个文件、一个测�?- 从推测性推理切换到直接观察

• 当失败是高风险或外部阻塞时，升级到人�? 不要声称不支持的自动修复操作，如"重置 Agent 状�?�?更新 harness 配置"，除非你真的通过当前环境中的真实工具在做这些�? **受控恢复检查清�?*�?

markdown

## Recovery Action
- Diagnosis chosen: [选择的诊断]
- Smallest action taken: [采取的最小操作]
- Why this is safe: [为什么这是安全的]
- What evidence would prove the fix worked: [什么证据能证明修复有效]

Phase 4: Introspection Report（内省报告）

以报告结束，使恢复对下一�?Agent 或人类可读�?

markdown

## Agent Self-Debug Report
- Session / task: [会话/任务]
- Failure: [失败描述]
- Root cause: [根因]
- Recovery action: [恢复操作]
- Result: success | partial | blocked
- Token / time burn risk: [token/时间消耗风险]
- Follow-up needed: [需要的后续]
- Preventive change to encode later: [后续要编码的预防措施]

恢复启发�?

按以下顺序优先选择干预措施�?

1. 用一句话重述真实目标
2. *验证世界状态，而不是信任记�?
3. 缩小失败范围
4. *运行一个判别性检�?
5. *然后才重�?

**坏模�?*�?- 用稍微不同的措辞重试相同操作三次

**好模�?*�?- 捕获失败

• 分类模式
• 运行一个直接检�?- 只有当检查支持时才改变计�?

与现有系统的集成

场景	调用
恢复后代码变�?	�?Backpressure 门控验证
失败模式值得学习	�?.learnings/ 记录
问题不是技术失败而是决策模糊	�?daily-agent 重新调度
失败来自冲突的本地状�?	�?workspace 审计

输出标准

当此技能激活时，不要只�?我修复了"结束�? 始终提供�?- 失败模式

• 根因假设
• 恢复操作
• 情况现在更好或仍然阻塞的证据