tophtab/nga-just-works/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.

Thinking Framework: Bayesian Reasoning

When multiple root causes are plausible and evidence is incomplete, update your beliefs proportionally to new evidence rather than clinging to initial assumptions.

Step 1: Establish Priors

Before investigating, state what you believe and why:

Priors must sum to 100%. If you can't assign probabilities, investigate first.

Step 2: Observe Evidence

Document what you found — be specific about reliability:

• What exactly did you observe?
• How reliable? (test output > log message > user report > hunch)
• Could multiple hypotheses explain this?

Step 3: Update Beliefs

For each hypothesis, ask: How likely is this evidence if this hypothesis were true?

Direction of update matters more than calculation:

• Evidence strongly predicted by H1 → H1 probability increases
• Evidence contradicts H2 → H2 probability decreases
• Evidence equally likely under all → no update

Step 4: Seek Discriminating Evidence

Don't gather more of the same. Find evidence that differs strongly between top hypotheses.

If H1 and H3 are close: "What would I see if H1 is true but not if H3 is true?" Then check for that.

Step 5: State Confidence

Never express binary certainty when evidence is incomplete. Use "most likely", "plausible but unlikely", "worth investigating".

Common Fallacies

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

1. Sync templates - After updating .trellis/spec/, sync to src/templates/markdown/spec/

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