debug

name	debug
description	Systematic bug investigation and fixing with hypotheses, root cause analysis, regression tests, and verification. Use when encountering bugs, errors, or unexpected behavior.
category	process
triggers	["fix bug","something broken","error","not working","test failing","unexpected behavior"]

Debug

Purpose: Systematic bug investigation and fixing Phases: Reproduce → Analyze → Narrow → Fix → Verify Usage: /debug [scope flags] <bug description>

Iron Laws

1. NO FIXES WITHOUT ROOT CAUSE — Never apply a fix without first identifying and confirming the root cause. Guessing is not debugging.
2. ANALYZE FIRST, FIX SECOND — AI excels at analysis but struggles when simultaneously diagnosing and fixing. Complete all analysis before proposing any fix.
3. EVERY BUG FIX NEEDS A REGRESSION TEST — A fix without a test is a fix that will break again.
4. THREE FAILURES MEANS RETHINK — If 3 fix attempts fail, the bug is a design problem. Stop patching and escalate.

When to Use

• Bug reports or error messages
• Test failures with unclear cause
• Unexpected runtime behavior
• Performance regressions

When NOT to Use

• Known fix, just needs implementation → /implement
• Adding new functionality → /implement
• Investigating code without a bug → /explore

Never Do

• Never suppress an error to "fix" it — Catching and ignoring is hiding, not fixing
• Never fix symptoms instead of root cause — If the symptom is a null pointer, the root cause is why it's null
• Never apply a fix you don't understand — "It works but I don't know why" means it will break again
• Never make multiple changes at once — Change one thing, verify, then change the next

Scope Flags

Flag	Description
--files=<paths>	Limit investigation to specific files
--branch=<name>	Compare against specific branch

Note: Command examples use npm as default. Adapt to the project's package manager per ai-assistant-protocol — Project Commands.

---

Phase 1: Reproduce

Mode: Read-only — gather symptoms and establish reproduction.

Step 1.1: Gather Symptoms

## Bug Investigation

1. **What's happening?** Expected vs. Actual
2. **When does it occur?** Always / Sometimes / Specific conditions
3. **Reproduction steps?**
4. **Recent changes?**

Wait for response.

Step 1.2: Establish Minimal Reproduction

Before investigating, identify the smallest possible reproduction case:

• What's the minimal input that triggers the bug?
• Can the bug be reproduced in a test?
• If a test reproduces it, that becomes the regression test.

Step 1.3: Confirm Understanding

**Issue:** [restate problem]
**Conditions:** [when it happens]
**Impact:** [who/what affected]

**Confirm understanding:** (yes / correct / clarify)

GATE: Wait for confirmation.

---

Phase 2: Analyze

Mode: Read-only — form hypotheses. Do NOT propose fixes yet.

Step 2.1: Form Hypotheses

## Hypotheses

1. **[Hypothesis A]** — Why: [reasoning] — Check: [how to verify]
2. **[Hypothesis B]** — Why: [reasoning] — Check: [how to verify]

Step 2.2: Investigate

Classify the bug by failure mode and use backward tracing to find the root cause (see references/debugging-techniques.md for failure taxonomy, and references/root-cause-tracing.md for the backward tracing methodology).

Context-Aware References

Load debugging references based on failure category:

Failure Category	Load References
Test failures / flaky tests	references/debugging-techniques.md (Test Polluter Detection)
Logic errors / wrong output	references/root-cause-tracing.md (Backward Tracing)
Type errors	typescript-guidelines
API integration issues	rest-api-guidelines, error-handling-guidelines
Security-related bugs	security-guidelines
Performance issues	performance-guidelines
Database / ORM errors	prisma-guidelines, references/debugging-techniques.md (Schema Drift Detection)

Use the debugging decision tree to select strategy:

Symptom	Strategy
Error message present	Read stack trace, trace to source
Intermittent failure	Suspect race condition, timing, shared state
Works locally, fails in CI	Environment difference (env vars, Node version)
Production-only failure	Check: (a) database schema/migration state, (b) environment variables, (c) connection strings, (d) Node.js version, (e) dependency versions, (f) server logs for full stack trace. Cannot reproduce locally? Analyze logs and schema diffs.
Worked before a specific date	git bisect to find breaking commit
Works for some inputs	Boundary analysis around failing input
Silent wrong output	Add logging at each transformation step
Performance regression	Profile first — don't guess

Step 2.3: Compare Working vs. Broken

Search for similar functionality that works correctly. Document differences.

git log --oneline -20 -- path/to/broken.ts

---

Phase 3: Narrow

Mode: Read-only — converge on root cause with user input.

Step 3.1: Present Analysis

## Analysis Results

**Investigated:** [what was checked]
**Eliminated:** [hypotheses ruled out and why]
**Most likely:** [remaining hypothesis with evidence]

Step 3.2: Narrow Focus with User

Ask the user to help eliminate hypotheses:

## Remaining Hypotheses

1. [Hypothesis X] — Evidence: [what supports it]
2. [Hypothesis Y] — Evidence: [what supports it]

**Narrow further:** (eliminate a hypothesis or suggest additional checks)

Step 3.3: Confirm Root Cause

## Root Cause

**Location:** `path/to/file.ts:42`
**Problem:** [what's wrong]
**Why:** [explanation]
**Evidence:** [findings that confirm this]

**Confirm root cause:** (yes / no / need more evidence)

GATE: Wait for confirmation before proposing fix.

---

Phase 4: Fix

Mode: Full access — implement the approved fix.

Step 4.1: Propose Fix

## Fix Plan

**Root Cause:** [brief summary]
**Solution:** [what will change]
**Files:** `path/to/file.ts` — [fix description]
**Regression Test:** Test for [scenario]
**Security impact:** [Does the fix touch input handling, auth, or data access? If yes, verify no security regression]
**Risks:** [any concerns]

---
**Approve fix?** (yes / no / modify)

GATE: Do NOT implement until user approves.

Step 4.2: Implement Fix

1. Apply fix — one change at a time
2. Run typecheck after change
3. Validate at multiple layers (see references/defense-in-depth.md for four-layer validation and related code audit)

Step 4.3: Add Regression Test

REQUIRED. The test should reproduce the bug scenario and assert correct behavior:

it('should [correct behavior] when [bug trigger condition]', () => {
  // Arrange: conditions that triggered the bug
  // Act: action that previously failed
  // Assert: correct behavior
});

Escalation Rule

Attempt	Action
1st failure	Re-examine root cause, form new hypothesis
2nd failure	Expand investigation scope, check assumptions
3rd failure	STOP. Present architectural concerns. Don't attempt another fix.

Present an escalation report:

## Escalation Report
**Bug:** [description]
**Attempts:** 3
**Hypotheses Tested:** [list with evidence for/against]
**Remaining Theories:** [what hasn't been ruled out]
**Suggested Next Steps:** [what a human should investigate]
**Architectural Concern:** [why this may be a design problem]

---

Phase 5: Verify

Mode: Testing + git operations.

Step 5.1: Run All Tests

npm run test -- path/to/file.spec.ts   # Regression test first
npm run test -- [affected-pattern]      # Related tests
npm run typecheck
npm run lint

Step 5.2: Verification Report

## Verification

| Check | Status |
|-------|--------|
| Regression test | ✓ Pass |
| Related tests | ✓ Pass (N tests) |
| Type check | ✓ Pass |
| Lint | ✓ Pass |

**Verify fix externally:** (confirmed working / still broken / partially fixed)

GATE: All tests must pass. Wait for user verification.

Step 5.3: Commit

Present commit message with root cause explanation and Fixes #issue reference.

GATE: Wait for explicit approval before committing.

---

Quick Reference

Phase	Mode	Gate
1. Reproduce	Read-only	User confirms symptoms
2. Analyze	Read-only	Hypotheses formed
3. Narrow	Read-only	User confirms root cause
4. Fix	Full access	User approves fix plan
5. Verify	Testing + git	All tests pass + user confirms

Acceptance Tests

ID	Type	Prompt / Condition	Expected
DBG-T1	Positive	"Login page throws 500 error"	Skill triggers
DBG-T2	Positive	"Tests are failing after merge"	Skill triggers
DBG-T3	Positive	"Button click does nothing"	Skill triggers
DBG-T4	Negative	"Add a new button to the form"	Does NOT trigger (→ /implement)
DBG-T5	Negative	"How does the auth module work?"	Does NOT trigger (→ /explore)
DBG-T6	Negative	"Review the error handling code"	Does NOT trigger (→ /review)
DBG-T7	Boundary	"Fix this and add a retry"	Triggers (bug fix primary)