debugging

name	debugging
version	1.2.0
status	implemented
description	调试阶段 - 系统化问题定位和修复 5步调试法：闻味道 → 揪头发 → 照镜子 → 执行 → 复盘 包含压力升级机制和7项检查清单 v1.2: 强化 context-aware 激活、memory_hints 复用与失败升级事件记录
tags	["phase","debugging","problem-solving"]
requires	{"tools":["Bash","Read","Write","Grep","Glob","Edit"]}

DEBUGGING

Preamble

{{include: ../_shared/preamble.md}}

Overview

DEBUGGING 阶段是 agentic-workflow 的系统化调试阶段，采用5步调试法进行问题定位和修复。

核心特点：

• 5步调试法：闻味道 → 揪头发 → 照镜子 → 执行 → 复盘
• 压力升级机制：2次失败切换方案，3次搜索+读源码，4次完整检查，5次+最小PoC
• 7项检查清单：日志、边界、并发、资源、配置、依赖、环境
• 铁律：穷尽一切、先做后问、主动出击
• 当前实现会根据 owned_files、diff 规模和失败历史调整调试档位：
  • 局部简单修复默认降到 0% / 25%
  • 复杂或重复失败才升级到 50%
  • syntax_error、type_error、quality_gate_failed、重复 test_failure 才会触发激活升级

Entry Criteria

进入 DEBUGGING 阶段的条件：

• 收到明确的 bug 报告或问题描述
• 遇到执行失败、错误异常或不符合预期的情况
• 从其他阶段转来的需要调试的问题

禁止在未完成 Phase 1（根因调查）前提出任何修复方案。 "我觉得可能是..." 不是根因。"代码第 42 行的条件判断在 X 场景下失效" 才是根因。

Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

Exit Criteria

退出 DEBUGGING 阶段的条件：

以下三项必须全部满足，缺一不可： 1. 根本原因已用具体 file:line 证据确认（不是猜测） 2. 修复后相关测试全部通过（必须运行并看到输出） 3. 复盘总结已记录（至少包含：根因 + 修复方案 + 预防措施）

Core Process

Step 0.5: Reflexion 检索 — 读取历史反思（新增）

对标 Reflexion (arXiv 2303.11366)：在开始调试前，先检索本项目过去的同类错误反思，避免重复踩坑。

# 层 1: 因果图检索 — 错误信号 → 已知修复方案（MAGMA Causal Graph 代理）
python3 scripts/memory_longterm.py \
  --op search-causal \
  --query "${错误信号，如: ModuleNotFoundError / TypeError unsupported |}" \
  --limit 3 2>/dev/null || true

# 层 2: 全量意图检索（包含因果图 + 结构化索引 + MEMORY.md fallback）
python3 scripts/memory_longterm.py \
  --op search \
  --query "${问题关键词，如: import error / type annotation / contract gate}" \
  --intent debug \
  --limit 3 2>/dev/null || true

处理规则：

• search-causal 有命中 → Fix 字段即为已验证解决方案，直接参考，跳过相同失败路径
• search 有命中 → 在 Step 1 分析中优先考虑历史教训
• 两者均无结果 → 正常进入 Step 1，调试结束后在 Step 5.5 写入新反思（自动触发图索引重建）

---

Step 1: 闻味道 (Sense the Problem)

目的：初步感知问题性质，建立调试方向

强制自动诊断 — 进入 DEBUGGING 时必须先执行以下命令收集信息：

# 1. 查看最近变更（可能引入 bug 的代码）
git diff HEAD~3 --stat
git log --oneline -5

# 2. 运行测试获取完整错误输出（根据项目类型选择）
python3 -m pytest --tb=long -q 2>&1 | tail -50   # Python
# npm test 2>&1 | tail -50                        # Node.js
# cargo test 2>&1 | tail -50                      # Rust

# 3. 检查 lint/type 错误
python3 -m ruff check . 2>&1 | head -20 || true

操作：

1. 收集错误信息（错误消息、堆栈跟踪、返回码）— 必须从上述命令输出中提取
2. 复现问题（确认问题可重现）
3. 确定问题域（前端/后端/数据库/网络/配置）
4. 评估紧急程度和影响范围

压力升级：

• 1次失败 → 继续 Step 2
• 2次失败 → 切换调试策略
• 3次失败 → 进入深度分析模式

输出：

• 问题复现步骤
• 初步问题分类
• 调试策略选择

---

Step 2: 揪头发 (Pull Hair - Root Cause Analysis)

目的：深入分析，找到根本原因

操作：

1. 5Why 分析法：连续追问5个为什么
2. 鱼骨图分析：人、机、料、法、环、测
3. 差异分析：对比正常和异常状态的差异点
4. 假设验证：提出假设并设计验证方案

假设驱动调查协议 (ACH)

当问题原因不明确时，使用竞争假设法：

7步调查流程：

1. 理解假设 - 明确假设成立需要满足的条件
2. 定义证据标准 - 确认证据 vs 否定证据 vs 模糊证据
3. 收集直接证据 - 搜索代码路径、数据流、配置
4. 收集支持证据 - 相关错误、日志、相似bug
5. 测试假设 - 构建最小复现场景
6. 评估置信度 - High(>80%)/Medium(50-80%)/Low(<50%)
7. 报告发现 - 包含因果链和证据引用

压力升级：

• 2次失败 → 切换方案
• 3次搜索+读源码
• 4次完整检查
• 5次+ → 最小PoC验证

输出：

• 根本原因定位
• 影响因子列表
• 验证方案

---

Step 3: 照镜子 (Self Reflection - Check Your Own Code)

目的：审视自身，排除自身引入的问题

操作：

1. 检查最近修改（git diff, 最近 commits）
2. 审查相关代码（边界条件、异常处理）
3. 验证假设（打印日志、断点调试）
4. 对比文档（实现是否符合设计文档）

7项检查清单：

#	检查项	检查内容
1	日志检查	是否有足够的日志定位问题？日志级别是否合适？
2	边界检查	边界条件是否正确处理？空值、极值、并发？
3	并发检查	是否有竞态条件？锁的使用是否正确？
4	资源检查	是否有资源泄漏？连接池、内存、文件句柄？
5	配置检查	配置是否正确加载？环境变量是否到位？
6	依赖检查	依赖版本是否兼容？API 是否变更？
7	环境检查	不同环境下行为是否一致？

输出：

• 自身代码审查结论
• 排除的嫌疑点列表
• 剩余可疑点优先级

Step 4.5: Simple-Failure Downgrade (新增)

对于明显的局部小修复，优先轻量调试而不是默认重型调试：

• 单文件、低依赖、错误信息明确 → 优先 0% / 25%
• 多文件联动、失败历史重复、根因不清 → 升到 50%
• 只有高价值疑难缺陷才进入完整上下文调试

---

Step 4: 执行 (Execute - Fix and Verify)

目的：实施修复并验证效果

操作：

1. 制定修复方案（最小修改原则）
2. 实施修复（遵循 immutable 原则）
3. 编写/更新测试用例
4. 执行测试验证
5. 交叉验证（其他测试是否受影响）

Boil the Lake：

• 修复必须包含完整测试覆盖
• 不能只修表面，要彻底解决问题
• 避免引入新的技术债务

输出：

• 修复内容说明
• 测试结果
• 风险评估

---

Step 5: 复盘 (Review - Learn from the Experience)

目的：总结经验，避免重蹈覆辙

操作：

1. 记录问题根因和修复方案
2. 提取可复用模式
3. 识别预防措施
4. 更新检查清单（如有新检查点）

复盘模板：

## 问题回顾
- 问题描述：
- 发生时间：
- 影响范围：

## 根因分析
- 直接原因：
- 根本原因：
- 5Why 追溯：

## 修复方案
- 修复内容：
- 验证方法：
- 测试覆盖：

## 经验教训
- 做得好的：
- 需要改进的：
- 预防措施：

输出：

• 复盘文档
• 更新建议
• 知识沉淀

---

Step 5.5: Reflexion Entry — 写入语言反思（新增）

对标 Reflexion (arXiv 2303.11366)：每次调试结束后生成结构化 verbal 反思，存入长期记忆，供下次同类问题检索使用。

反思格式（Reflexion paper Algorithm 1 对齐）：

当 [具体触发场景/错误类型] 时，
我错误地 [具体错误行为/错误假设]。
正确做法应该是 [正确行为]，
因为 [根本原因]。
下次遇到 [关键识别特征] 应立即 [正确行动]。

写入命令：

python3 scripts/memory_longterm.py \
  --op add-experience \
  --exp "Task:[问题类型] Trigger:[触发场景] Mistake:[错误行为] Fix:[正确做法] Signal:[识别特征]" \
  --confidence 0.7 \
  --scope project

示例：

python3 scripts/memory_longterm.py \
  --op add-experience \
  --exp "Task:type-annotation Trigger:Python 3.9 union syntax \
  Mistake:used str|Path without __future__ import \
  Fix:add 'from __future__ import annotations' at module top \
  Signal:TypeError unsupported operand type(s) for |"

何时可以跳过：

• DONE 状态且问题极简单（typo 级别）→ 可跳过
• 其他情况一律写入

---

AskUserQuestion Format

{{include: ../_shared/ask-user-question.md}}

Boil the Lake

{{include: ../_shared/boil-the-lake.md}}

Completion Status Protocol

状态定义

状态	含义	使用场景
DONE	完成	问题已定位、修复、验证，测试通过
DONE_WITH_CONCERNS	完成但有顾虑	修复完成但有未解决的边缘情况或技术债务
BLOCKED	阻塞	无法继续调试（缺信息、缺工具、缺权限）
NEEDS_CONTEXT	需要更多上下文	需要用户提供额外信息才能继续

状态转换

[开始调试]
    │
    ▼
┌─────────────────────────────────┐
│  分析中...                       │
│  (执行 5步调试法)                │
└─────────────────────────────────┘
    │
    ▼
┌──────────────────────────────────────────────────────┐
│  状态判断：                                          │
│  ├─ 问题修复且测试通过 → DONE                        │
│  ├─ 有边缘问题待后续 → DONE_WITH_CONCERNS            │
│  ├─ 缺关键信息/工具   → NEEDS_CONTEXT → 用户询问     │
│  └─ 无法解决           → BLOCKED → 升级             │
└──────────────────────────────────────────────────────┘

输出格式

## DEBUGGING Completion Report

### 问题摘要
- **问题描述**: [简述]
- **影响范围**: [影响范围]
- **紧急程度**: P0/P1/P2/P3

### 调试过程
- **调试轮次**: N 次
- **使用策略**: [使用的调试策略]
- **关键发现**: [1-2个关键发现]

### 修复结果
- **修复方案**: [描述]
- **测试覆盖**: [覆盖情况]
- **风险评估**: [风险]

### 最终状态
- **Completion Status**: [DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT]
- **后续行动**: [如需要]

---

Hypothesis Generation Framework

当问题原因不明确时，使用竞争假设法（ACH）生成和验证假设。

6 类失败模式

生成假设时，覆盖以下 6 类失败模式：

类别	描述	检查点
Logic Error	算法错误、边界问题、off-by-one	条件判断、循环、数据结构
Data Issue	类型错误、空值、编码问题	输入验证、类型转换、空值处理
State Problem	竞态条件、缓存过期、状态初始化	并发、缓存、初始化逻辑
Integration Failure	API契约、版本不兼容、配置错误	接口调用、版本、配置
Resource Issue	内存泄漏、连接池耗尽、超时	资源管理、连接、限流
Environment	依赖缺失、权限问题、时区	依赖、环境变量、权限

证据标准

证据类型	强度	示例
Direct	强	代码在 file.ts:42 显示 if (x > 0) 应为 if (x >= 0)
Correlational	中	错误率在 commit abc123 后增加
Testimonial	弱	"在我机器上能跑"
Absence	可变	代码路径中未找到空值检查

置信度评估

级别	标准
High (>80%)	多条直接证据，清晰因果链，无矛盾证据
Medium (50-80%)	部分直接证据，合理因果链，轻微歧义
Low (<50%)	大部分相关证据，因果链不完整，存在矛盾证据

假设验证流程

1. 生成 N 个假设（覆盖不同失败模式）
2. 每个假设定义：
   - 确认证据：什么证据会确认此假设？
   - 否定证据：什么证据会否定此假设？
3. 收集证据，标注强度和来源
4. 评估置信度
5. 仲裁：比较所有假设，确定最可能根因

铁律提醒

在 DEBUGGING 阶段必须遵守：

铁律	要求	检查点
穷尽一切	没有穷尽所有方案之前，禁止说"无法解决"	尝试了多少种调试方案？
先做后问	遇到问题先自行搜索、读源码、验证，再提问	搜索了多少文档/源码？
主动出击	端到端交付，不只是"刚好够用"	修复是否完整？测试覆盖够吗？