打破循环 - 深度 Bug 分析

当调试完成后，使用此 Skill 进行深度分析，打破"修 Bug → 遗忘 → 重复"的循环。

分析框架

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

1. 根因分类

这个 Bug 属于哪个类别？

类别	特征	示例
A. 规范缺失	没有文档说明该怎么做	新功能没有检查清单
B. 跨层契约	层与层之间的接口不清晰	API 返回的格式与预期不同
C. 变更传播失败	改了一处，漏了其他地方	改了函数签名，漏了调用点
D. 测试覆盖缺口	单元测试通过，集成测试失败	单独运行正常，组合起来就挂
E. 隐式假设	代码依赖未文档化的假设	时间戳秒 vs 毫秒

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

如果你在成功之前尝试了多次修复，分析每次失败：

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

3. 预防机制

什么机制可以防止这类问题再次发生？

类型	描述	示例
文档	写下来让大家知道	更新思维指南
架构	从结构上让错误不可能发生	类型安全的包装器
编译时	TypeScript strict，禁止 any	签名变更导致编译错误
运行时	监控、告警、扫描	检测孤立实体
测试覆盖	E2E 测试、集成测试	验证完整流程
代码审查	检查清单、PR 模板	"你检查了 X 吗？"

4. 系统性扩展

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

•类似问题：其他地方是否存在同样的问题？
•设计缺陷：是否存在根本性的架构问题？
•流程缺陷：开发流程是否需要改进？
•知识缺口：团队是否缺少某些理解？

5. 知识沉淀

将洞察固化到系统中：

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

输出格式

请按以下格式输出分析：

markdown

## Bug 分析：[简短描述]

### 1. 根因分类
- **类别**：[A/B/C/D/E] - [类别名称]
- **具体原因**：[详细描述]

### 2. 修复失败原因（如适用）
1. [第一次尝试]：[失败原因]
2. [第二次尝试]：[失败原因]
...

### 3. 预防机制
| 优先级 | 机制 | 具体行动 | 状态 |
|--------|------|----------|------|
| P0 | ... | ... | TODO/DONE |

### 4. 系统性扩展
- **类似问题**：[列出有类似问题的地方]
- **设计改进**：[架构层面的建议]
- **流程改进**：[开发流程的建议]

### 5. 知识沉淀
- [ ] [需要更新的文档 / 需要创建的工单]

核心理念

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

三个层次的洞察：

•战术层：如何修复这个 Bug
•战略层：如何预防这类 Bug
•哲学层：如何拓展思维模式

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

分析之后：立即行动

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

•
更新 spec/guides - 不要只列 TODO，要实际更新相关文件：
- •如果是跨平台问题 → 更新 cross-platform-thinking-guide.md
- •如果是跨层问题 → 更新 cross-layer-thinking-guide.md
- •如果是代码复用问题 → 更新 code-reuse-thinking-guide.md
- •如果是领域特定的 → 更新 backend/*.md 或 frontend/*.md
•
同步模板 - 更新 .trellis/spec/ 后，同步到 src/templates/markdown/spec/
•
提交规范更新 - 这才是主要产出，不只是分析文本

分析如果只停留在聊天记录里就毫无价值。价值在于更新后的规范。