---
name: trellis-break-loop
description: "Analyze recurring bugs or failed fixes to identify a supported cause and targeted prevention; use for a requested debugging retrospective."
---

# Learn From A Debugging Loop

Use the current task's evidence and existing analysis. An ordinary fix with adequate regression coverage does not automatically need a separate retrospective or new spec section.

Distinguish the observed failure, supported cause and remaining hypotheses. Explain earlier failed fixes only when they change the diagnosis. Consider missing contracts, cross-layer mismatch, missed consumers, inadequate coverage or an implicit assumption; these are prompts, not mandatory categories.

When causes compete, choose a small check whose outcome distinguishes them. Preserve counterevidence, input/environment differences and failed runs. Do not invent numerical priors or confidence thresholds, or call a plausible explanation proven. Stop expanding the investigation when the authorized problem and meaningful regression are covered; new risks become scoped follow-up work.

Choose the smallest useful prevention: correct the shared contract, add a behavioral regression, enforce an invariant or improve a specific diagnostic. Reuse existing protections. Similar symptoms warrant a targeted consumer check, not automatic repository-wide cleanup or a new abstraction.

Keep run chronology and unresolved hypotheses in the current task. Use `trellis-update-spec` only for a new, reusable lesson, updating its existing owner rather than duplicating it across spec and guides. Summarize cause, evidence, prevention and remaining limitations at the depth the problem needs.

Retrospective work does not authorize commits, archival, deployment, real-data operations or edits to an upstream template repository. Preserve project approval and independent-review requirements.