trellis-break-loop

打破循环——深度 Bug 分析

调试完成后，使用此方法进行深度分析，打破“修复 Bug → 忘记 → 重复”的循环。

---

分析框架

从以下 5 个维度分析刚修复的 Bug：

1. 根因类别

此 Bug 属于哪一类？

类别	特征	示例
A. 缺少规范	没有关于如何处理的文档	新功能缺少检查清单
B. 跨层契约	层与层之间的接口不明确	API 返回的格式与预期不同
C. 变更传播失败	只修改了一处，遗漏了其他位置	修改了函数签名，却遗漏了调用点
D. 测试覆盖缺口	单元测试通过，集成测试失败	单独运行正常，组合使用时出错
E. 隐式假设	代码依赖未记录的假设	时间戳单位是秒还是毫秒

2. 修复失败的原因（如适用）

如果你在成功前尝试了多种修复方法，请分析每次失败的原因：

• 表面修复：修复了症状，而非根因
• 范围不完整：找到了根因，却未覆盖所有情况
• 工具局限：grep 未能找到，类型检查不够严格
• 思维模型：一直在同一层查找，没有考虑跨层问题

3. 预防机制

哪些机制可以防止此问题再次发生？

类型	说明	示例
文档	记录下来，让大家知晓	更新思维指南
架构	从结构上杜绝错误	类型安全包装器
编译时	严格类型检查，不留逃逸通道	签名变更会导致编译错误
运行时	监控、告警、扫描	检测孤立实体
测试覆盖	E2E 测试、集成测试	验证完整流程
代码评审	检查清单、PR 模板	“是否检查了 X？”

4. 系统性扩展

此 Bug 揭示了哪些更广泛的问题？

• 类似问题：其他哪些地方可能存在此问题？
• 设计缺陷：是否存在根本性的架构问题？
• 流程缺陷：开发流程是否有改进空间？
• 知识缺口：团队是否缺少某些认知？

5. 知识沉淀

将经验固化到系统中：

• 更新 .trellis/spec/guides/ 思维指南
• 更新相关的 .trellis/spec/ 文档
• 创建问题记录（如适用）
• 为根因修复创建功能工单
• 按需更新检查指南

---

输出格式

请按以下格式输出分析：

## Bug Analysis: [Short Description]

### 1. Root Cause Category
- **Category**: [A/B/C/D/E] - [Category Name]
- **Specific Cause**: [Detailed description]

### 2. Why Fixes Failed (if applicable)
1. [First attempt]: [Why it failed]
2. [Second attempt]: [Why it failed]
...

### 3. Prevention Mechanisms
| Priority | Mechanism | Specific Action | Status |
|----------|-----------|-----------------|--------|
| P0 | ... | ... | TODO/DONE |

### 4. Systematic Expansion
- **Similar Issues**: [List places with similar problems]
- **Design Improvement**: [Architecture-level suggestions]
- **Process Improvement**: [Development process suggestions]

### 5. Knowledge Capture
- [ ] [Documents to update / tickets to create]

---

核心理念

调试的价值不在于修复 Bug，而在于让这一类 Bug 永远不再发生。

三个层次的洞见：

1. 战术层面：如何修复这个 Bug
2. 战略层面：如何预防这一类 Bug
3. 哲学层面：如何拓展思维模式

花 30 分钟分析，可以节省未来 30 小时的调试时间。

思维框架：贝叶斯推理

当多个根因都合理且证据不完整时，应根据新证据按比例更新判断，而不是固守最初的假设。

步骤 1：设定先验概率

调查之前，说明你的判断及理由：

假设	先验概率	推理
H1：[原因 A]	40%	此类问题中最常见的原因
H2：[原因 B]	30%	结合当前环境来看合理
H3：[其他原因]	30%	兜底项

先验概率总和必须为 100%。如果无法分配概率，请先进行调查。

步骤 2：观察证据

记录你的发现，并具体说明其可靠性：

• 你具体观察到了什么？
• 可靠性如何？（测试输出 > 日志消息 > 用户反馈 > 直觉）
• 多个假设是否都能解释这些现象？

步骤 3：更新信念

针对每个假设，询问：如果这个假设为真，这些证据出现的可能性有多大？

更新的方向比计算更重要：

• H1 强烈预测了这些证据 → H1 的概率上升
• 证据与 H2 相矛盾 → H2 的概率下降
• 在所有假设下出现的可能性都相同 → 不更新

步骤 4：寻找区分性证据

不要收集更多同类证据。寻找在不同头部假设之间差异显著的证据。

如果 H1 和 H3 难以区分：“如果 H1 为真而 H3 为假，我会看到什么？”然后去查证。

步骤 5：说明置信度

置信度	行动
90%+	继续修复，并进行监控
70-90%	继续处理，并添加回退检查
50-70%	提交前验证假设
<50%	需要更多证据，不要猜测

证据不完整时，切勿表达非黑即白的确定性。使用“最有可能”“有可能但不太可能”“值得调查”等表述。

常见谬误

谬误	示例	修正
忽视基础概率	“测试失败 → 代码有问题”	测试因其他原因失败的频率有多高？
确认偏误	“肯定是竞争条件，我来找竞争条件的证据”	主动寻找反驳首选假设的证据
锚定效应	“上次是缓存问题，这次大概也是缓存问题”	根据当前上下文，而不是昨天的 Bug，确定先验概率

---

分析后：立即采取行动

重要：完成上述分析后，必须立即：

1. 更新规范/指南 - 不要只列出待办事项，要实际更新相关文件：

   • 如果是跨平台问题 → 更新 cross-platform-thinking-guide.md
   • 如果是跨层问题 → 更新 cross-layer-thinking-guide.md
   • 如果是代码复用问题 → 更新 code-reuse-thinking-guide.md
   • 如果是特定领域问题 → 更新 backend/*.md 或 frontend/*.md

2. 同步模板 - 更新 .trellis/spec/ 后，同步到 src/templates/markdown/spec/

3. 提交规范更新 - 这是主要产出，而不只是分析文本

如果分析只留在聊天中，就毫无价值。真正的价值在于更新后的规范。