break-loop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Break the Loop - Deep Bug Analysis

打破循环——深度Bug Analysis

When debug is complete, use this command for deep analysis to break the "fix bug -> forget -> repeat" cycle.

当调试完成后，使用此命令进行深度分析，打破「修复Bug→遗忘→重复犯错」的循环。

Analysis Framework

分析框架

Analyze the bug you just fixed from these 5 dimensions:

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

1. Root Cause Category

1. 根因类别

Which category does this bug belong to?

Category	Characteristics	Example
A. Missing Spec	No documentation on how to do it	New feature without checklist
B. Cross-Layer Contract	Interface between layers unclear	API returns different format than expected
C. Change Propagation Failure	Changed one place, missed others	Changed function signature, missed call sites
D. Test Coverage Gap	Unit test passes, integration fails	Works alone, breaks when combined
E. Implicit Assumption	Code relies on undocumented assumption	Timestamp seconds vs milliseconds

该Bug属于哪一类别？

类别	特征	示例
A. 缺失规范	没有相关操作文档	无检查清单的新功能
B. 跨层契约问题	各层间接口定义不清晰	API返回格式与预期不符
C. 变更传播遗漏	修改了一处但遗漏其他关联点	修改函数签名后，遗漏调用位置
D. 测试覆盖缺口	单元测试通过，但集成测试失败	单独运行正常，组合使用时出错
E. 隐含假设	代码依赖未文档化的假设	时间戳秒级与毫秒级混淆

2. Why Fixes Failed (if applicable)

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

If you tried multiple fixes before succeeding, analyze each failure:

Surface Fix: Fixed symptom, not root cause
Incomplete Scope: Found root cause, didn't cover all cases
Tool Limitation: grep missed it, type check wasn't strict
Mental Model: Kept looking in same layer, didn't think cross-layer

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

表面修复：只修复了症状，未解决根因
范围不全：找到了根因，但未覆盖所有场景
工具限制：grep遗漏内容，类型检查不够严格
思维局限：一直在同一层排查，未考虑跨层问题

3. Prevention Mechanisms

3. 预防机制

What mechanisms would prevent this from happening again?

Type	Description	Example
Documentation	Write it down so people know	Update thinking guide
Architecture	Make the error impossible structurally	Type-safe wrappers
Compile-time	TypeScript strict, no any	Signature change causes compile error
Runtime	Monitoring, alerts, scans	Detect orphan entities
Test Coverage	E2E tests, integration tests	Verify full flow
Code Review	Checklist, PR template	"Did you check X?"

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

类型	描述	示例
文档完善	记录相关内容以便他人知晓	更新思维指南
架构优化	从结构上避免错误发生	类型安全包装器
编译时检查	TypeScript严格模式，禁用any类型	签名变更触发编译错误
运行时监控	监控、告警、扫描	检测孤立实体
测试覆盖增强	端到端测试、集成测试	验证完整流程
代码评审规范	检查清单、PR模板	「你是否检查了X？」

4. Systematic Expansion

4. 系统性拓展

What broader problems does this bug reveal?

Similar Issues: Where else might this problem exist?
Design Flaw: Is there a fundamental architecture issue?
Process Flaw: Is there a development process improvement?
Knowledge Gap: Is the team missing some understanding?

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

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

5. Knowledge Capture

5. 知识沉淀

Solidify insights into the system:

Update
```
.trellis/spec/guides/
```
thinking guides
Update
```
.trellis/spec/cli/backend/
```
or
```
cli/frontend/
```
docs
Create issue record (if applicable)
Create feature ticket for root fix
Update check commands if needed

将洞察固化到系统中：

更新
```
.trellis/spec/guides/
```
下的思维指南
更新
```
.trellis/spec/cli/backend/
```
或
```
cli/frontend/
```
下的文档
创建问题记录（如适用）
创建根因修复的需求工单
如有需要，更新检查命令

Output Format

输出格式

Please output analysis in this format:

markdown

undefined

请按照以下格式输出分析结果：

markdown

undefined

Bug Analysis: [Short Description]

1. Root Cause Category

Category: [A/B/C/D/E] - [Category Name]
Specific Cause: [Detailed description]

Category: [A/B/C/D/E] - [Category Name]
Specific Cause: [Detailed description]

2. Why Fixes Failed (if applicable)

[First attempt]: [Why it failed]
[Second attempt]: [Why it failed] ...

[First attempt]: [Why it failed]
[Second attempt]: [Why it failed] ...

3. Prevention Mechanisms

Priority	Mechanism	Specific Action	Status
P0	...	...	TODO/DONE

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]

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]

---

[Documents to update / tickets to create]

---

Core Philosophy

核心理念

The value of debugging is not in fixing the bug, but in making this class of bugs never happen again.

Three levels of insight:

Tactical: How to fix THIS bug
Strategic: How to prevent THIS CLASS of bugs
Philosophical: How to expand thinking patterns

30 minutes of analysis saves 30 hours of future debugging.

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

三个层次的洞察：

战术层：如何修复当前这个Bug
战略层：如何预防此类Bug
理念层：如何拓展思维模式

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

After Analysis: Immediate Actions

分析完成后：立即行动

IMPORTANT: After completing the analysis above, you MUST immediately:

Update spec/guides - Don't just list TODOs, actually update the relevant files:
- If it's a cross-platform issue → update
```
cross-platform-thinking-guide.md
```
- If it's a cross-layer issue → update
```
cross-layer-thinking-guide.md
```
- If it's a code reuse issue → update
```
code-reuse-thinking-guide.md
```
- If it's domain-specific → update
```
cli/backend/*.md
```
  or
```
cli/frontend/*.md
```

Sync templates - After updating

.trellis/spec/

, sync to

src/templates/markdown/spec/

Commit the spec updates - This is the primary output, not just the analysis text

The analysis is worthless if it stays in chat. The value is in the updated specs.

重要提示：完成上述分析后，你必须立即执行以下操作：

更新spec/guides文档 - 不要只列出待办事项，实际更新相关文件：
- 如果是跨平台问题 → 更新
```
cross-platform-thinking-guide.md
```
- 如果是跨层问题 → 更新
```
cross-layer-thinking-guide.md
```
- 如果是代码复用问题 → 更新
```
code-reuse-thinking-guide.md
```
- 如果是领域特定问题 → 更新
```
cli/backend/*.md
```
  或
```
cli/frontend/*.md
```

同步模板 - 更新

.trellis/spec/

后，同步到

src/templates/markdown/spec/

提交spec更新 - 这是核心产出，而不仅仅是分析文本

如果分析内容只停留在聊天记录里，那就毫无价值。价值体现在更新后的规范文档中。