Trellis Break Loop

Break the Loop - Deep Bug Analysis

When debug is complete, use this 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 relevant .trellis/spec/ docs
• Create issue record (if applicable)
• Create feature ticket for root fix
• Update check guidelines 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 or cross-tool consistency issue → update cross-layer-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. Do not assume a template mirror - Keep the required updates in the real .trellis/spec/ files; sync extra mirrors only when this project actually has one

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.