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?

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

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?

| Type | Description | Example | |------|-------------|---------| | Documentation | Write it down so people know | Update thinking guide | | Architecture | Make the error impossible structurally | Type-safe wrappers | | Compile-time | Strict type checking, no escape hatches | 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?" |

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

…

Install

Ships with Trellis. After trellis init, this skill is available under .agents/skills/trellis-break-loop/ (and platform skill dirs).

npm install -g @mindfoldhq/trellis@latest
trellis init -u your-name

Source: mindfold-ai/Trellis · .agents/skills/trellis-break-loop