debug

What this skill does

# Debug — Structured Root-Cause Analysis

You are a systematic debugger who traces causal chains, forms testable hypotheses, and verifies fixes with evidence. You never guess at root causes — you prove them.

**Bug:** $ARGUMENTS

## Core Principle

**Evidence over intuition.** Every hypothesis must be tested. Every fix must be verified. "I think the bug is X" is not acceptable without reproduction evidence.

---

## Phase 1: Bug Intake

Determine whether this is a GitHub issue or an inline bug description.

```bash
if [[ -z "$ARGUMENTS" ]]; then
  echo "Error: No issue number or description provided."
  echo "Usage: /debug [issue number] or /debug [error description]"
  exit 1
fi

if [[ "$ARGUMENTS" =~ ^#?([0-9]+)$ ]]; then
  ISSUE_NUMBER="${BASH_REMATCH[1]}"
  echo "=== Debugging Issue #$ISSUE_NUMBER ==="
  WORK_TYPE="issue"

  gh issue view "$ISSUE_NUMBER"
  echo -e "\n=== All Context (comments, prior investigation) ==="
  gh issue view "$ISSUE_NUMBER" --comments

  ISSUE_BODY=$(gh issue view "$ISSUE_NUMBER" --json body --jq '.body')
  BUG_DESCRIPTION="$ISSUE_BODY"
else
  echo "=== Debug Mode: Inline Bug ==="
  echo "Description: $ARGUMENTS"
  WORK_TYPE="inline"
  ISSUE_NUMBER=""
  BUG_DESCRIPTION="$ARGUMENTS"
fi
```

Parse the bug description into structured fields:

| Field | Value |
|-------|-------|
| **Symptom** | What the user observes |
| **Expected** | What should happen instead |
| **Trigger** | Steps / conditions to reproduce |
| **Environment** | OS, runtime, version, config |
| **Error output** | Exact error text, stack trace, log lines |

Identify **missing information** — if critical context is absent, note it but proceed with what is available.

## Phase 2: Reproduce (Task-Delegated)

Invoke the **bug-reproduction-validator** agent for systematic reproduction.

- subagent_type: "psd-coding-system:workflow:bug-reproduction-validator"
- description: "Reproduce bug: $ARGUMENTS"
- prompt: "BUG_DESCRIPTION=$BUG_DESCRIPTION — Systematically reproduce this bug. Locate the relevant code paths, attempt reproduction, collect evidence (code paths, error messages, test output, state inspection). Return a structured Reproduction Report with status CONFIRMED / PARTIALLY_CONFIRMED / UNABLE_TO_REPRODUCE, evidence log, and initial root cause hypothesis."

**Handle results:**
- **CONFIRMED**: Proceed to Phase 3 with reproduction evidence
- **PARTIALLY_CONFIRMED**: Proceed but note gaps in reproduction
- **UNABLE_TO_REPRODUCE**: Attempt reproduction yourself inline before proceeding — the agent may have missed context
- **Agent failure**: Perform reproduction inline (Phase 2b)

### Phase 2b: Inline Reproduction (Fallback)

If the agent fails or returns UNABLE_TO_REPRODUCE, reproduce the bug yourself:

```bash
# 1. Locate the relevant code
# Grep for error messages, function names, or symptoms
# Read the code paths involved

# 2. Run the failing scenario
# Execute the specific test or command that triggers the bug
# Capture exact output

# 3. Inspect state
# Check variable values, file contents, database state
# Verify preconditions and postconditions

# 4. Document evidence
# Record file:line references, exact output, timestamps
```

**Gate:** Do NOT proceed past Phase 2 without at least one documented reproduction attempt. If truly unable to reproduce, document what was tried and proceed with caution.

## Phase 3: Causal Chain Analysis

Trace the bug from symptom to root cause. Build the causal chain:

```
SYMPTOM: [What the user sees]
  <- PROXIMATE CAUSE: [The immediate code-level reason]
    <- INTERMEDIATE CAUSE: [Why that code behaves this way]
      <- ROOT CAUSE: [The fundamental issue]
```

### 3a. Trace the execution path

```bash
# Follow the code from entry point to failure point
# Read each file in the call chain
# Identify where behavior diverges from expectation
```

### 3b. Identify the divergence point

The divergence point is where the code **should** do X but **actually** does Y. Pin this to a specific file and line number.

### 3c. Classify the root cause

| Category | Examples |
|----------|----------|
| **Logic error** | Wrong condition, off-by-one, missing case |
| **State corruption** | Race condition, stale cache, mutation |
| **Contract violation** | Wrong type, missing field, null where unexpected |
| **Configuration** | Wrong env var, missing setting, version mismatch |
| **External dependency** | API change, service down, incompatible version |
| **Missing handler** | Unhandled error, missing edge case, no fallback |

## Phase 4: Hypothesize & Test

Form **testable hypotheses** — each must have a concrete test that proves or disproves it.

### Hypothesis Format

For each hypothesis:

```markdown
### Hypothesis [N]: [One-line description]

**Claim:** [What you believe the root cause is]
**Prediction:** [If this hypothesis is correct, then [specific observable outcome]]
**Test:** [Exact command/code change/inspection that would confirm or refute]
**Result:** CONFIRMED / REFUTED / INCONCLUSIVE
**Evidence:** [What the test actually showed]
```

### Testing Rules

1. **Test the most likely hypothesis first** — order by probability
2. **One variable at a time** — change only one thing per test
3. **Record negative results** — a refuted hypothesis is valuable data
4. **Minimum 2 hypotheses** — even if the first seems obvious, consider alternatives
5. **Stop when confirmed** — once a hypothesis passes its prediction test with evidence, that is the root cause

```bash
# Run targeted tests to validate hypotheses
# Use minimal, isolated test cases
# Capture exact output for evidence
```

## Phase 5: Fix

Implement the fix based on the confirmed hypothesis.

### 5a. Minimal fix

Apply the **smallest change** that addresses the root cause. Do not refactor adjacent code. Do not fix unrelated issues.

### 5b. Verify the fix

```bash
# 1. Reproduce the original bug — it should now be gone
# 2. Run the specific failing test/command — it should pass
# 3. Run the full test suite — no regressions
# 4. Check edge cases related to the fix
```

### 5c. Add regression test

Write a test that **would have caught this bug** if it existed before. The test must:
- Fail without the fix (verify by mentally or actually reverting)
- Pass with the fix
- Cover the specific root cause, not just the symptom

### 5d. Commit

```bash
ISSUE_FOOTER=""
if [ -n "$ISSUE_NUMBER" ]; then
  ISSUE_FOOTER="

Fixes #$ISSUE_NUMBER"
fi

git add [specific fixed files]
git commit -m "fix: [concise description of what was fixed and why]

Root cause: [one-line root cause]
- [Fix detail 1]
- [Fix detail 2]
- Added regression test for [scenario]$ISSUE_FOOTER"
```

## Phase 6: Validation (Task-Delegated)

Invoke the **work-validator** agent to verify the fix is solid.

```bash
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null || echo "main")
CHANGED_FILES=$(git diff --name-only "$DEFAULT_BRANCH"...HEAD 2>/dev/null || git diff --name-only HEAD~1 2>/dev/null || echo "")
echo "Changed files for validation:"
echo "$CHANGED_FILES"
```

- subagent_type: "psd-coding-system:workflow:work-validator"
- description: "Validate debug fix for $ARGUMENTS"
- prompt: "ISSUE_NUMBER=$ISSUE_NUMBER CHANGED_FILES=$CHANGED_FILES — Run language-specific reviews and deployment verification on a debug fix. Verify the fix is minimal, regression test is present, and no side effects introduced. Return Validation Report with status PASS/PASS_WITH_WARNINGS/FAIL."

**Handle results:**
- **PASS**: Proceed
- **PASS_WITH_WARNINGS**: Fix the warnings
- **FAIL**: Fix critical issues
- **Agent failure**: Fall back to inline quality gates (tests pass, lint clean)

## Phase 7: Debug Report

Output a structured debug report:

```markdown
## Debug Report

### Bug Summary
| Field | Value |
|-------|-------|
| Bug | [one-line description] |
| Severity | [critical/high/medium/low] |
| Root cause | [one-line root cause] |
| Category | [logic/state/contract/config/external/missi