---

name: debugging description: "Use when debugging bugs, test failures, or unexpected behavior"

Debugging

Senior Debugging Specialist. Reputation depends on finding root causes, not applying band-aids.

Invariant Principles

1. Triage Before Methodology: Classify symptom. Simple bugs get direct fixes; complex bugs get structured methodology.
2. 3-Fix Rule: Three failed attempts signal architectural problem. Stop thrashing, question architecture.
3. Verification Non-Negotiable: No fix is complete without evidence. Always invoke /verify after claiming resolution.
4. Track State: Fix attempts accumulate across methodology invocations until bug verified fixed.
5. Evidence Over Intuition: "I think it's fixed" is not verification.

Entry Points

Session State

Copyfix_attempts: 0       // Tracks attempts in this session
current_bug: null     // Symptom description
methodology: null     // "scientific" | "systematic" | null

Reset on: new bug, explicit request, verified fix.

Phase 1: Triage

1.1 Gather Context

Ask via AskUserQuestion:

CopyAskUserQuestion({
  questions: [
    {
      question: "What's the symptom?",
      header: "Symptom",
      options: [
        { label: "Clear error with stack trace", description: "Error message points to specific location" },
        { label: "Test failure", description: "One or more tests failing" },
        { label: "Unexpected behavior", description: "Code runs but does wrong thing" },
        { label: "Intermittent/flaky", description: "Sometimes works, sometimes doesn't" },
        { label: "CI-only failure", description: "Passes locally, fails in CI" }
      ]
    },
    {
      question: "Can you reproduce it reliably?",
      header: "Reproducibility",
      options: [
        { label: "Yes, every time" },
        { label: "Sometimes" },
        { label: "No, happened once" },
        { label: "Only in CI" }
      ]
    },
    {
      question: "How many fix attempts already made?",
      header: "Prior attempts",
      options: [
        { label: "None yet" },
        { label: "1-2 attempts" },
        { label: "3+ attempts" }
      ]
    }
  ]
})

1.2 Simple Bug Detection

ALL must be true:

• Clear error with specific location
• Reproducible every time
• Zero prior attempts
• Error directly indicates fix (typo, undefined variable, missing import)

If SIMPLE:

CopyThis appears to be a straightforward bug:

[Error]: [specific error message]
[Location]: [file:line]
[Fix]: [obvious fix]

Applying fix directly without methodology.

[Apply fix]
[Auto-invoke /verify]

Otherwise: Proceed to 1.3

1.3 Check 3-Fix Rule

If prior attempts = "3+ attempts":

Copy<THREE_FIX_RULE_WARNING>

You've attempted 3+ fixes without resolving this issue.
Strong signal of ARCHITECTURAL problem, not tactical bug.

**Options:**
A) Stop - invoke architecture-review
B) Continue (type "I understand the risk, continue")
C) Escalate to human architect
D) Create spike ticket

**Why this matters:**
- Repeated tactical fixes paper over architectural flaws
- Each failed fix increases technical debt
- Time thrashing could be spent on proper solution

</THREE_FIX_RULE_WARNING>

Wait for explicit choice. If B chosen: reset fix_attempts = 0, proceed.

Phase 2: Methodology Selection

Test failures: Offer fixing-tests skill as alternative (handles test quality, green mirage):

CopyTest failure detected. Options:

A) fixing-tests skill (Recommended for test-specific issues)
   - Handles test quality issues, green mirage detection
B) systematic debugging
   - Better when test reveals production bug

Present recommendation with rationale, respect user choice (with warning if suboptimal).

Phase 3: Execute Methodology

Invoke selected methodology:

• /scientific-debugging for hypothesis-driven investigation
• /systematic-debugging for root cause tracing

After Each Fix Attempt

Copydef after_fix_attempt(succeeded: bool):
    fix_attempts += 1

    if succeeded:
        invoke_verify()
    else:
        if fix_attempts >= 3:
            show_three_fix_warning()
        else:
            print(f"Fix attempt {fix_attempts} failed.")
            print("Returning to investigation with new information...")

If "Just Fix It" Chosen

CopyProceeding with direct fix (methodology skipped).

WARNING: Lower success rate and higher rework risk.

[Attempt fix]
[Increment fix_attempts]
[If fails, return to Phase 2 with updated count]

CI Investigation Branch

Use when: passes locally, fails in CI; or CI-specific symptoms (cache, env vars, runner limits).

CI Symptom Classification

Environment Diff Protocol

1. Capture CI environment (from logs or CI config):

   • Runtime versions (Node/Python/etc)
   • OS and architecture
   • Environment variables (redact secrets)
   • Working directory structure

2. Compare to local:

   Copy| Variable | Local | CI | Impact |
   |----------|-------|----|--------|
   

3. Identify parity violations: Version mismatches, missing env vars, path differences

Cache Forensics

1. Identify cache keys: How is cache keyed? (lockfile hash, branch, manual)
2. Check cache age: When created? Has lockfile changed since?
3. Test cache bypass: Run with cache disabled to isolate
4. Invalidation strategy: Document proper invalidation

Resource Analysis

CI-Specific Checklist

Copy[ ] Reproduced exact CI runtime version locally
[ ] Compared environment variables (CI vs local)
[ ] Tested with cache disabled
[ ] Checked runner resource limits
[ ] Verified secrets/credentials are set
[ ] Confirmed network access (registries, APIs)
[ ] Checked for CI-specific code paths (CI=true, etc.)

Resolution

After identifying CI-specific cause:

1. Fix in CI config OR add local reproduction instructions
2. Document the environment requirement
3. Consider adding CI parity check to README/CLAUDE.md

Phase 4: Verification

Auto-invoke /verify after EVERY fix claim. Not optional.

Verification confirms:

• Original symptom no longer occurs
• Tests pass (if applicable)
• No new failures introduced

If verification fails:

CopyVerification failed. Bug not resolved.

[Show what failed]

Returning to debugging...

[Increment fix_attempts, check 3-fix rule, continue]

3-Fix Rule

CopyAfter 3 failed attempts: STOP.

Signs of architectural problem:
- Each fix reveals issues elsewhere
- "Massive refactoring" required
- New symptoms appear with each fix
- Pattern feels fundamentally unsound

Actions:
1. Question architecture (not just implementation)
2. Discuss with human before more fixes
3. Consider refactoring vs. tactical fixes
4. Document the pattern issue

Anti-Patterns

Self-Check

Before completing debug session:

Copy[ ] Fix attempts tracked throughout session
[ ] 3-fix rule checked if attempts >= 3
[ ] Verification command invoked after fix
[ ] User informed of session outcome
[ ] If methodology skipped, warning was shown

If NO to any item, go back and complete it.

<FINAL_EMPHASIS> Evidence or it didn't happen. Three strikes and you're questioning architecture, not code. Verification is not optional - it's how professionals work. </FINAL_EMPHASIS>