name: break-loop description: “破环分析 - 深度错误分析”
破环分析 - 深度错误分析
当调试完成后，使用此命令进行深度分析，以打破“修复错误 -> 遗忘 -> 重复”的循环。
分析框架
从以下5个维度分析您刚修复的错误：
1. 根因类别
此错误属于哪一类别？
| 类别 | 特征 | 示例 |
|---|---|---|
| A. 缺少规范 | 没有文档说明如何操作 | 新功能无检查清单 |
| B. 跨层契约 | 层间接口不清晰 | API返回格式与预期不同 |
| C. 变更传播失败 | 更改一处，遗漏其他 | 更改函数签名，遗漏调用点 |
| D. 测试覆盖缺口 | 单元测试通过，集成测试失败 | 单独工作，组合时崩溃 |
| E. 隐含假设 | 代码依赖未文档化的假设 | 时间戳秒 vs 毫秒 |
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/ -
提交规范更新 - 这是主要输出，而不仅仅是分析文本
如果分析停留在聊天中，则毫无价值。价值在于更新的规范中。