name: break-loop description: “打破循环 - 深度错误分析”

打破循环 - 深度错误分析

当调试完成后，使用此技能进行深度分析，以打破“修复错误 -> 忘记 -> 重复”的循环。

分析框架

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

1. 根本原因类别

这个错误属于哪个类别？

类别	特征	示例
A. 缺失规范	没有如何执行的文档	没有清单的新功能
B. 跨层契约	层之间的接口不清晰	API返回的格式与预期不同
C. 更改传播失败	更改了一个地方，遗漏了其他	更改函数签名，遗漏调用点
D. 测试覆盖缺口	单元测试通过，集成测试失败	单独工作，组合时失败
E. 隐含假设	代码依赖于未记录的假设	时间戳秒与毫秒

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

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

表面修复：修复了症状，而非根本原因
不完整的范围：找到了根本原因，但没有覆盖所有情况
工具限制：grep遗漏了，类型检查不严格
思维模型：一直在同一层寻找，没有考虑跨层

3. 预防机制

什么机制可以防止这种情况再次发生？

类型	描述	示例
文档	写下来让人知道	更新思考指南
架构	使错误结构上不可能	类型安全的包装器
编译时	TypeScript严格，无any	签名更改导致编译错误
运行时	监控、警报、扫描	检测孤立实体
测试覆盖	E2E测试，集成测试	验证完整流程
代码审查	清单，PR模板	“你检查X了吗？”

4. 系统化扩展

这个错误揭示了什么更广泛的问题？

类似问题：这个问题可能在其他地方存在吗？
设计缺陷：是否有根本的架构问题？
过程缺陷：是否有开发过程改进？
知识缺口：团队是否缺少一些理解？

5. 知识捕获

将洞察固化到系统中：

[ ] 更新 .trellis/spec/guides/ 思考指南
[ ] 更新 .trellis/spec/backend/ 或 frontend/ 文档
[ ] 创建问题记录（如适用）
[ ] 创建根本修复的功能票据
[ ] 如有需要，更新检查技能

输出格式

请以下列格式输出分析：

## 错误分析：[简短描述]

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

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

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

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

### 5. 知识捕获
- [ ] [要更新的文档/要创建的票据]

核心哲学

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

三个层面的洞察：

战术的：如何修复这个错误
战略的：如何预防这类错误
哲学的：如何扩展思维模式

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

分析后：立即行动

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

更新规范/指南 - 不要只列出待办事项，实际更新相关文件：
- 如果是跨平台问题 → 更新 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/
提交规范更新 - 这是主要输出，不仅仅是分析文本

如果分析停留在聊天中，它就毫无价值。价值在于更新的规范。