debug

The bug is in the USER'S PROJECT. You are debugging their code, not Claude Code itself. Do not disclaim or reframe the issue as a tool/assistant problem.

Do NOT attempt any fix before completing root cause investigation. No exceptions. If you catch yourself thinking "let me just try changing this" — stop and go back to Phase 1.

Debug

Find the root cause, then fix it. Not the other way around.

The bug is in the user's project — you are debugging their code and environment, not Claude Code or any tool in the assistant infrastructure.

When to Self-Invoke

Invoke this skill automatically when:

• The user pastes an error message or stack trace
• A test failure occurs during execute
• Build or lint fails unexpectedly
• The user describes unexpected behavior, even casually ("this is weird", "why is X happening")
• A fix just shipped and the user replies with a terse failure signal — "still broken", "not fixed", "doesn't work", "nope", a one-word rejection, or a bare screenshot. Do not patch again; the short dismissal means the last fix missed the root cause. Drop into Phase 1.

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

If you haven't completed Phase 1, you cannot propose fixes. This is not optional. This is not skippable because it "looks obvious." Obvious bugs have root causes too.

Phase 1 — Root Cause Investigation

Phase 1 requires tool calls, not speculation. Read the code, run the commands, check the diff. Do not hypothesize about what the code does without reading it — that is guessing dressed up as analysis.

1. Read error messages completely. Stack traces, line numbers, error codes. Don't skip past them. They often contain the answer.
2. Reproduce consistently. Exact steps, every time. If you can't reproduce, gather more data — don't guess.
3. Check recent changes. Git diff, recent commits, new dependencies, config changes, environmental differences.
4. Gather evidence in multi-component systems. Log at each component boundary. Run once. Analyze where data goes wrong. Don't guess which layer is broken.
5. Trace data flow. Find where bad values originate. Trace upstream to the source. Fix at source, not at symptom.

Phase 2 — Pattern Analysis

1. Find working examples of similar code in the codebase.
2. Compare working vs broken — list every difference, however small. Don't assume "that can't matter."
3. Understand dependencies and assumptions the code makes.

Phase 3 — Hypothesis and Testing

1. Form a single hypothesis: "X is the root cause because Y." Be specific.
2. Test minimally — the smallest possible change, one variable at a time.
3. If it works, proceed to Phase 4. If not, form a new hypothesis. Do not stack fixes.

Phase 4 — Implementation

1. Write a failing test that reproduces the bug.
2. Implement a single fix addressing the root cause.
3. Verify — test passes, no regressions.
4. If 3+ fix attempts have failed: stop. This is not a failed hypothesis — this is likely a wrong architecture. Discuss with the user before attempting more fixes.

Research Integration

If the bug involves an external API or library behaving unexpectedly, invoke meridian:research to verify expected behavior against live docs before forming hypotheses. Don't assume you know how the library works.

Red Flags — Stop and Restart Phase 1

If you catch yourself thinking any of these, you've skipped the process:

• "Quick fix for now, investigate later"
• "Just try changing X and see"
• "I don't fully understand but this might work"
• "Here are the main problems: [lists fixes without investigation]"
• Proposing solutions before tracing data flow
• 3+ fix attempts in different places revealing new problems each time

When the Process Reveals No Root Cause

If systematic investigation reveals the issue is truly environmental, timing-dependent, or external:

1. You've completed the process — that's fine
2. Document what you investigated
3. Implement appropriate handling (retry, timeout, error message)
4. Consider invoking meridian:document to capture the investigation for future sessions

Most "no root cause" verdicts turn out to be incomplete investigation. Treat the conclusion with skepticism — it's the convenient answer, not usually the right one.

Integration

• Predecessors: meridian routing, or direct invocation
• Successors: commit (if fix applied)
• May invoke: research
• On completion: Re-evaluate the next user message against the routing table. Common next: commit.