debug

# Debug Skill Systematic investigation methodology for failures. Follows a structured reproduce → isolate → hypothesize → test → record cycle. Escalates after **2 consecutive failed debug cycles**. ## 1. Invocation Criteria Use this skill when any of the following apply: | Trigger | Example | |---------|---------| | **Build failure** | Compilation error, `dotnet build` fails, `npm run build` fails | | **Test failure** | Tests that were passing now fail; flaky test behavior | | **Unexpected agent behavior** | Agent produces output inconsistent with spec or prior runs | | **Drift-related error** | `sync-dotgithub.ps1` reports differences; `audit-catalog.ps1` fails unexpectedly | ## 2. Investigation Step Sequence Execute steps in order. Do not skip steps. 1. **Reproduce**: Confirm the failure is deterministic. Run the failing command again from a clean state. If intermittent, capture conditions under which it occurs. 2. **Isolate**: Narrow the failure scope. Which file, function, or check is failing? What changed since the last known-good state? (`git diff` or `git log --oneline -5`) 3. **Hypothesize**: Form one specific hypothesis about the root cause. Write it down: *"I believe X is failing because Y."* 4. **Test hypothesis**: Make a minimal targeted change or investigation step to confirm or reject the hypothesis. Do NOT make sweeping changes. 5. **Record finding**: Document: - What was tested - What was observed (actual vs. expected) - Hypothesis status: **CONFIRMED** or **REJECTED** - If rejected: form a new hypothesis and return to step 3 ## 3. Output Format After completing an investigation cycle, produce a structured findings report: ``` ## Debug Findings — <date> **Failure**: [brief description of the failure] **Reproduced**: [Yes / No / Intermittent] **Isolated to**: [file / function / check / component] **Hypothesis**: [your hypothesis] **Test performed**: [what you did to test it] **Result**: [CONFIRMED / REJECTED] **Root cause** (if confirmed): [explanation] **Fix applied**: [description of change made, or "none — escalating"] **Remaining issue** (if unresolved): [what is still unknown or broken] ``` ### Escalation Trigger If the fix is applied and the check still fails, that completes **1 debug cycle**. After **2 consecutive failed debug cycles** (attempt corrective action → rerun check → still fails = 1 cycle), the agent **must** terminate the debug loop and escalate to a human. Do NOT autonomously initiate a third cycle. **Escalation message format**: ``` ⚠️ ESCALATION REQUIRED — 2 debug cycles attempted without resolution. Failure: [description] Cycle 1: [hypothesis + fix attempted + result] Cycle 2: [hypothesis + fix attempted + result] Unresolved: [what is still broken] Recommended next step: [human investigation / revert to last known-good / ask for expert input] ``` ## 4. Escalation Threshold The escalation threshold is **2 consecutive failed debug cycles**. This is a fixed number — not a variable, not "a few", not "several". **Definition of one debug cycle**: hypothesis formed → corrective action taken → verification check rerun → check still fails. **Why 2?** After 2 cycles without resolution, the agent is likely stuck in a local minimum. Human judgment is needed to break the loop. **What NOT to do**: - Do NOT run a third cycle autonomously - Do NOT silently continue without escalating - Do NOT expand scope of changes hoping something will work