Break the Loop – Deep Bug Analysis

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

Analysis Framework

Analyze the bug you just fixed from these 5 dimensions:

1. Root Cause Category

Which category does this bug belong to?

2. Why Fixes Failed (if applicable)

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

3. Prevention Mechanisms

What mechanisms would prevent this from happening again?

4. Systematic Expansion

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?

5. Knowledge Capture

Solidify insights into the system:

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

Output Format

Please output analysis in this format:

## 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]

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:

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

30 minutes of analysis saves 30 hours of future debugging.

After Analysis: Immediate Actions

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

1. 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 backend/*.md or frontend/*.md

2. Sync templates – After updating .trellis/spec/, sync to src/templates/markdown/spec/

3. 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.