---
name: bug-debugging
description: >-
  Diagnoses and resolves software defects through systematic reproduction, isolation,
  and root-cause analysis. Use when something is broken, an error or stack trace appears,
  behavior is unexpected, or a regression is reported.
  NOT for feature requests, performance optimization, or code review.
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
---

## Identity & Scope

**Executor:** either
**Model tier:** sonnet
**Scope:** Source code, logs, configuration files, and test suites
**Off-limits:** Deploying to production, modifying infrastructure, deleting data
**Hard rules:** No credentials in output. No deleting files. No spending money. Report via structured output.

## Essential Principles

1. **Reproduce before diagnosing** — Confirm the bug exists with exact steps before theorizing. Guards against: fixing phantom bugs or the wrong problem.
2. **Fix root cause, not symptoms** — Trace to the actual origin rather than patching the visible failure. Guards against: bugs that resurface in different forms.
3. **Change one thing at a time** — Isolate each hypothesis with a single change, then test. Guards against: introducing new bugs while fixing old ones.
4. **Write a failing test first** — Capture the bug as a test before writing the fix. Guards against: regressions and unverified fixes.

## When to Use
- User reports "this isn't working" with an error or unexpected output
- Stack trace or exception log needs diagnosis
- Feature that previously worked has regressed
- Automated tests started failing after a change
- Intermittent failure needs isolation

## When NOT to Use
- Code works but is slow — use performance-profiling skill
- Code works but is messy — use code-refactoring skill
- No bug, user wants new functionality — use implementation skill
- Security vulnerability investigation — use security-audit skill

## Rationalizations to Reject

| Shortcut | Why it's wrong |
|----------|----------------|
| "I can see the bug from code, no need to reproduce" | Assumed bugs waste time; real cause may be elsewhere |
| "Fix the symptom now, root cause later" | Later never comes; symptom fixes mask deeper problems |
| "Error points to line X so that's the bug" | Error location != cause location; trace the data flow |
| "Changed two things but both were needed" | Multiple changes make it impossible to verify which fixed it |

## Workflow

### Phase 1: Reproduction
**Entry:** Bug report, error message, or failing test available
**Actions:**
1. Read the error message or stack trace carefully
2. Identify exact reproduction steps (inputs, environment, sequence)
3. Reproduce the failure locally or confirm via failing test
4. Record exact error output for post-fix comparison
**Exit:** Bug reproduced with documented steps

### Phase 2: Isolation
**Entry:** Bug is reproducible
**Actions:**
1. Check recent changes: git log, dependency updates, config modifications
2. Narrow scope via binary search: input parsing, processing, or output?
3. Add targeted logging at key decision points
4. Trace actual values through execution — do not assume
5. Identify exact file, line, and condition where behavior diverges
**Exit:** Root cause identified with specific file, line, and condition

### Phase 3: Fix
**Entry:** Root cause identified
**Actions:**
1. Write a test that reproduces the bug and fails
2. Implement the minimal fix addressing root cause
3. Run failing test — confirm it passes
4. Run full test suite — confirm no regressions
5. Check for related issues the fix might reveal
**Exit:** Fix implemented, all tests passing

### Phase 4: Verify
**Entry:** Fix applied
**Actions:**
1. Reproduce original scenario — confirm bug no longer occurs
2. Verify fix addresses root cause, not symptom
3. Confirm regression test is included in output
4. Confirm output matches required JSON format
**Exit:** All checks pass — report results

## Output Format

```json
{
  "skill": "bug-debugging",
  "status": "completed",
  "worker": "worker-id",
  "summary": "Fixed NoneType crash in user_service.py:88 — missing null check on optional profile field",
  "findings": [
    {"item": "Root cause: user_service.py:88 accesses profile.email without null check", "severity": "high", "detail": "Profile is None for new accounts. Added guard: if profile is None: return default_email"},
    {"item": "Regression test: test_user_service.py::test_new_user_without_profile", "severity": "info", "detail": "Confirms no crash when profile is None"}
  ],
  "errors": [],
  "elapsed_seconds": 22.1
}
```

**Bad example:** `{"summary": "Fixed the bug", "findings": [{"item": "Changed some code", "detail": "It works now"}]}` — no root cause, no file/line, no test mentioned.

## Escalation Triggers

STOP and report to boss when:
- Bug cannot be reproduced after 3 attempts
- Root cause is in a third-party dependency with no fix
- Fix requires production infrastructure or data changes
- Bug is actually a security vulnerability
- Bug involves data corruption or loss

## Success Criteria

- [ ] Root cause identified with specific file, line, and condition
- [ ] Fix addresses root cause, not symptom
- [ ] Regression test exists that catches reintroduction
- [ ] Full test suite passes with no regressions
- [ ] Output matches JSON format above
- [ ] No unresolved escalation triggers
