---

name: legion-debug description: Diagnose stubborn or repeatedly misdiagnosed bugs from causal evidence. Use when plausible fixes have failed or observed behavior contradicts the explanation. For a requested fix, diagnose first and then continue implementation; diagnosis-only requests remain read-only. metadata: source-skill: debug source-sha256: "b467023932ce8cda5e677e208379f0f9233c50044e4882af7c3652e0f6029357" edition: "2026-09-06"

Debug

Find what is true, not merely a plausible story.

Preserve the reported behavior as an observation. Keep it separate from every explanation proposed by the user, earlier agents, tests, documentation, code structure, or yourself. Do not quietly replace an awkward symptom with one that better fits the code.

Treat hypotheses as questions, not findings. AI strongly prefers a cognitively inexpensive explanation that sounds technically credible and permits the investigation to close. Plausibility is not causal evidence. The apparent scale, cost, or strangeness of a symptom does not imply a correspondingly large or sophisticated cause.

Tests, names, comments, types, architecture, and prior diagnoses are historical claims about the system. They may guide attention, but they do not get to exclude possibilities unless current evidence independently establishes what they claim. A passing test proves only that the tested assertion passed under its constructed conditions.

When the bug becomes stubborn

If the bug has survived multiple intelligent attempts, stop increasing the complexity of the explanation. Assume the search space is wrong.

Repeated failure is evidence that an assumption may have been promoted from “probably true” to “not worth checking.” Deliberately inspect what everyone knows cannot be wrong. Temporarily revoke the authority of passing tests, familiar architecture, confident prior explanations, and apparently trivial foundations. Start looking everywhere you know it is not.

This reset is not an invitation to generate a longer list of speculative edge cases. Return to the shortest account of the observed reality and question the premises that made the simple causes seem unavailable. A stubborn investigation often becomes difficult because the simple cause was excluded, not because the defect itself is complex.

Causal standard

Do not report a root cause merely because the source contains behavior compatible with a hypothesis. A root cause should be supported by evidence showing the mechanism from cause to observed failure and should account for the material observations without contradiction. Prefer a direct causal probe when one is safe and proportionate.

If the evidence establishes only a hypothesis, call it a hypothesis and say what remains unproved. An honest unresolved diagnosis is better than a confident guess.

Keep diagnosis distinct from repair. A diagnosis-only request remains read-only. If the current request already asks to fix the problem, establishing the cause completes this diagnostic phase, not the task: continue the scoped repair and verification without asking the person to authorize it again. Do not infer a broader refactor from one defect. Communicate the observed behavior, demonstrated cause or remaining uncertainty, connecting evidence, and confidence. Routine failures with an obvious, directly evidenced cause need no additional ceremony.