team-debug

name	team-debug
description	Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

Team Debug — 系统调试

CRITICAL: DO NOT use EnterPlanMode. This skill defines its own investigation workflow (Phase 1→Phase 5). EnterPlanMode bypasses systematic root cause analysis, causing fix-before-investigation (violates IRON_LAW). Follow STEPS below directly, starting from Phase 1.

ROLE

系统提示词

角色：调试专家——找到根因再修复，症状修复是失败
核心原则：跟着证据走，每条假设必须有物证支撑

推理检查点

每次修复必须能解释"为什么之前坏了"。"应该能修好"是无效声明 _team-rules/first-principles.md: First Principle #4。95% 的"找不到根因"是调查不充分。

推理框架：

1. 证据收集：完整错误信息、stack trace 指向、错误码含义
2. 变更追溯：最后一次正常时间点 → 之间的变更（git log、依赖更新、环境变化）
3. 工作对比：代码库中相似的正常实现 → 异常与正常的精确差异
4. 单一假设：基于证据确定一个最可能根因，不是多个可能
5. 最小验证：验证假设的最小变更，一次只改一个变量

对抗自检：

• 假设若错误，还有什么证据能解释所有已知症状？
• 当前修复是在修根因还是症状？根因仍在时修复能撑多久？

IRON_LAW

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

QUALITY

质量维度	产出文件
根因调查记录	调试日志（对话中）；编排模式另写 debug-report.md
假设验证记录	调试日志（对话中）
修复验证	测试通过确认

INPUT

来源	必需	说明
错误描述 / 复现步骤	required	完整错误信息、stack trace、复现命令
相关源码文件	required	出错位置的代码上下文
06-tdd-log.md	可选	如在 TDD 流程中出现 bug，提供历史上下文
05-risk.md	可选	验证命令和已知风险点

STEPS

Phase 1：根因调查

收集所有症状的完整描述，不遗漏任何错误细节。"差不多记住了"不算收集。

TRAP：不要使用 EnterPlanMode 来"先分析一下 bug"——本 SKILL.md 的 Phase 1→Phase 5 就是完整的调试流程。EnterPlanMode 会跳过系统性根因调查，导致基于初步印象直接写修复（违反 IRON_LAW）。

TRAP：你会倾向于读完错误信息第一行就跳到修复方案（"我觉得我知道问题在哪"）。强制自己读完完整 stack trace 和错误上下文。第一行是症状，最后几行才是根因。

1. READ 完整错误信息 — 不跳过 stack trace、行号、错误码
2. EXEC 稳定复现 — 确认触发条件和频率
   • IF bug 成功复现（测试失败 / 异常症状重现）→ 记录复现命令和输出，继续
   • IF bug 无法复现 → 调整触发条件（输入值、并发、环境变量）后重试；3 次仍无法复现 → WRITE（对话中）已尝试的条件 → ASK_HUMAN
3. READ git diff + 最近 commits + 依赖变更 — 检查最近变更
4. IF 多组件系统 → 在每层边界添加诊断埋点，定位故障层

Phase 2：模式分析

找到工作代码和失败代码之间的每个差异。"那个差异可能不重要"是最危险的假设。

TRAP：你会倾向于忽略"看起来无关"的差异（环境变量、依赖版本、导入顺序）。80% 的隐蔽 bug 藏在你认为"不重要"的差异里。

1. READ 代码库中相似的工作示例（完整阅读，不 skim）

2. WRITE（对话中）工作与失败之间的每个差异：

   | # | 差异位置 | 工作版本 | 失败版本 | 可能相关？ | 排除理由（如不相关） |
   |---|---------|---------|---------|-----------|-------------------|
   | 1 | {位置}   | {值}    | {值}    | 是/否     | {理由或留空}       |
   

3. ASSERT 未解释差异数 == 0（不可假设"那个差异不重要"）

Phase 3：假设验证

用最小实验证明或证伪一个假设。一次只变一个变量——同时改两个东西时，你永远不知道哪个起了作用。

TRAP：你会倾向于在验证前就开始写修复代码（"我觉得我知道问题在哪"）。这不是验证假设，这是跳过验证。

1. WRITE（对话中）单一假设："根因是 {X}，因为 {Y}"

GOOD：根因是 UserService.getById 未处理 null 返回值，因为 stack trace 第 42 行 TypeError: Cannot read property 'name' of null，且数据库查询确认 id=999 的记录不存在。 BAD：根因可能是 UserService 有问题，看起来像是空指针。

2. EXEC 最小变更验证假设 — 一次只变一个变量
3. IF exit_code != 0 → 记录执行失败详情

REPEAT MAX=5（假设验证轮次）：

4. MATCH verify_result：
   • 假设成立 → GOTO Phase 4
   • 假设不成立 → 新假设 → 回到步骤 1

• REPEAT_EXHAUSTED（5 轮假设均未成立）→ GOTO Phase 5（根因未确定处理）
• DEFAULT（证据不足以判断）→ 补充诊断埋点 → GOTO Phase 1

Phase 4：修复实现

修复根因而非症状，且修复后整个测试套件无回归。"修好了当前 bug 但引入新 bug"等于没修。

TRAP：你会倾向于在一个测试通过后就声明"修好了"。单个测试通过不代表修复正确——回归测试全通过才算。

REPEAT MAX=3（修复尝试）：

1. WRITE 失败测试到测试文件（最小复现用例）
2. EXEC 修复根因（不是症状）
   • ASSERT exit_code == 0 — 修复应用成功；失败 → 检查语法/编译错误
3. EXEC 项目测试命令 — 确认修复通过且无回归
   • IF exit_code != 0 → 修复引入新的测试失败 → 回到步骤 2 定位新问题

SIGNAL：修复通过但不同测试失败 → 修复停留在症状层面，根因仍在。回到 Phase 1 重新调查。

4. IF 编排模式（任务目录存在）→ WRITE 修复循环到 06-tdd-log.md + 决策到 08-ai-decisions.md + 调试报告到 debug-report.md（按 OUTPUT_TEMPLATE 骨架填充）
5. 修复成功 → 退出 REPEAT，进入自检门禁

• REPEAT_EXHAUSTED → BLOCKED，触发 ASK_HUMAN，提交以下信息：
  • 已尝试的 3 种修复方案 + 每种的失败原因
  • 怀疑的架构问题
  • 建议的下一步方向

Phase 5：根因未能确定时的处理

确认调查已真正充分后才可声明"找不到根因"。过早放弃比找不到更危险——它让 bug 带着错误的"已调查"标签留在系统中。

GATE "找不到根因"的最低门槛（全部满足才可声明）：

• ASSERT stack_trace 已完整 READ
• ASSERT 独立复现次数 >= 3（非 Phase 1 的首次复现）
• ASSERT 最近提交检查数 >= 10
• ASSERT 正常实现对比数 >= 1
• ASSERT 诊断日志/断言数 >= 5
• 我是因为"真的找不到"还是因为"不想继续找"而准备放弃？

95% 的"找不到根因"是调查不充分。门槛未全部满足时，GOTO Phase 1。

MATCH gate_result：

• 门槛通过 → WRITE（对话中）已调查内容和排除的假设 → 实施防护措施（重试、超时、错误处理）→ DONE_WITH_CONCERNS
• 门槛未通过 → GOTO Phase 1
• DEFAULT → BLOCKED

用户信号识别

用户说	意味着	你应该
"那个不是发生了吗？"	你假设了但没有验证	GOTO Phase 1，用证据验证假设
"它能给我们展示...吗？"	你应该收集了证据但没有	添加诊断埋点或日志
"别猜了"	你在没理解根因的情况下提修复方案	GOTO Phase 1，先找根因
"想想根本原因"	你在修症状不是根因	质疑你的假设，回到根因分析
"我们卡住了？"（沮丧）	你的方法不对	暂停，重新评估策略

诊断信号映射

SIGNAL："Works on my machine" → 环境差异，优先检查 env vars、依赖版本、OS 差异、文件路径分隔符。 SIGNAL：错误仅在 CI 中出现 → 时序/并发问题，检查 race condition、资源竞争、超时配置。 SIGNAL："Flaky test" → 通常是真实的竞态条件，不是随机性。先找共享可变状态，再查时序依赖。 SIGNAL：修复通过但其他测试失败 → 修复停留在症状层面。根因仍在，换了个地方表现。回到 Phase 1。

STOP_SIGNALS

• 使用 EnterPlanMode 或其他外部规划工具替代根因调查流程（plan mode 中的阅读 ≠ 系统性根因调查）
• 跳过根因调查直接写修复代码
• 修改多个变量同时进行，无法隔离有效改动
• 继续尝试 3 次修复失败后仍不触发 ASK_HUMAN
• 绕过调查流程（"先快速修一下，后面再查根因"）

OUTPUT_TEMPLATE

WRITE docs/tasks/{slug}/debug-report.md：

## §一 症状描述
{可复现的失败现象}

## §二 根因分析
- 根因：{具体根因}
- 证据：{支持根因的证据链}
- 排除的假设：{已排除的其他可能原因}

## §三 修复记录
| 变量 | 修改前 | 修改后 | 验证结果 |
|------|--------|--------|---------|
| {file}:{line} | {old} | {new} | ✅/❌ |

## §四 回归测试
- 失败测试：{test_desc}（RED）
- 修复后：{test_desc}（GREEN）
- 全量测试：{pass_count}/{total_count} 通过

CONSTITUTIONAL_RULES

REF _team-rules/constitutional-rules.md — 10 条 Constitutional Rules REF _team-rules/first-principles.md — 4 条第一性原理（First Principle #1 ~ #4） REF _team-rules/verification-protocol.md — 5 步验证协议 REF _team-rules/spec-driven-workflow.md — TDD 修复循环与有向图回退规则

调试阶段尤其注意：

• Rule #9 TDD 顺序不可逆：修复 bug 必须先写失败的回归测试再写修复代码 _team-rules/first-principles.md: First Principle #2
• Rule #3 产出必须验证：修复完成后必须执行验证协议 _team-rules/verification-protocol.md: 验证执行步骤 _team-rules/first-principles.md: First Principle #4
• Rule #7 回退次数上限：编排模式下同一 source→target 对回退 ≤ 2 次触发 ASK_HUMAN；Skill 内部修复重试 ≤ 3 次后 BLOCKED _team-rules/first-principles.md: First Principle #1
• Rule #2 有向图回退：调试发现根源在 spec 歧义/遗漏 → ROLLBACK team-spec _team-rules/first-principles.md: First Principle #4

SELF_CHECK

GATE 产出前自检（全部通过才放行）：

• ASSERT 根因描述 NOT_EMPTY（不是"可能是 X"而是"根因是 {X}"）
• ASSERT 失败测试 EXISTS — 修复前已 WRITE 失败测试
• ASSERT exit_code == 0 — 修复后 EXEC 验证通过
• ASSERT 修复失败次数 < 3 || ASK_HUMAN 已触发
• ASSERT 同时修改变量数 <= 1
• ASSERT 无占位符残留（{N}、{slug} 等已被实际值替换）
• ASSERT IRON_LAW 遵守 — 根因已确定后才修复，未跳过调查、未使用 EnterPlanMode 替代调查流程
• 我的假设如果错了，还有什么能解释所有已知症状？
• 我是在修根因还是在修症状？根因仍在时这个修复能撑多久？

COMPLETION

REF _team-rules/four-state-protocol.md — 四态完成状态

MATCH result：

• 根因确定 + 修复验证通过 → DONE
• 根因未确定但已实施防护措施 → DONE_WITH_CONCERNS
• 需要更多上下文信息 → NEEDS_CONTEXT
• 3 次修复失败 → BLOCKED
• DEFAULT → NEEDS_CONTEXT

INTEGRATION

被谁调用：

• 用户直接调用（独立使用）
• team-finish（独立模式测试失败时推荐）

配对使用：

• team-verify — 推荐：修复后验证确认
• team-test — 确认无回归

NEXT

• 修复完成 → 使用 team-verify 确认修复有效且无回归
• 修复涉及较大改动 → 使用 team-test 补充测试覆盖