# Trellis Break Loop

Deep bug analysis to break the fix-forget-repeat cycle.

- Repository: https://github.com/mindfold-ai/Trellis (15078 stars)
- Category: Engineering
- License: AGPL-3.0
- Last updated: 2026-09-29
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add mindfold-ai/Trellis --skill trellis-break-loop -g -a claude-code -y`
Codex: `npx skills add mindfold-ai/Trellis --skill trellis-break-loop -g -a codex -y`
Cursor: `npx skills add mindfold-ai/Trellis --skill trellis-break-loop -g -a cursor -y`
Gemini CLI: `npx skills add mindfold-ai/Trellis --skill trellis-break-loop -g -a gemini-cli -y`

## Description

Deep bug analysis to break the fix-forget-repeat cycle. Analyzes root cause category, why fixes failed, prevention mechanisms, and captures knowledge into specs. Use after fixing a bug to prevent the same class of bugs.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

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

The rest: https://github.com/mindfold-ai/Trellis/blob/HEAD/.agents/skills/trellis-break-loop/SKILL.md