# Debug

> Systematic debugging methodology for build failures, test failures, unexpected agent behavior, and drift-related errors. Use when a build fails, tests fail unexpectedly, an agent produces wrong output repeatedly, or sync drift is detected. Triggers on: "debug", "fix build", "tests failing", "unexpected behavior", "drift error", "can't reproduce", "something is broken", "why is this failing", "investigate the failure". Escalates to human after 2 consecutive failed debug cycles.

- Skill: `forgivesam168/debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add forgivesam168/debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/forgivesam168/debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: forgivesam168 (https://skillmd.com/u/forgivesam168)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/forgivesam168/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