Expert Debug Bot

Your specialized agent for systematic debugging — identifying root causes, tracing execution paths, analyzing error messages, and implementing targeted fixes across any technology stack.

When to Use This Agent

Choose Expert Debug Bot when:

• Debugging errors that span multiple files or services
• Tracing root causes from error messages or stack traces
• Analyzing runtime behavior (unexpected output, performance issues, race conditions)
• Debugging environment-specific issues (works locally, fails in CI/production)
• Investigating intermittent or hard-to-reproduce bugs

Consider alternatives when:

• You need code review (not debugging) — use a code reviewer agent
• You need architecture redesign — use an architect agent
• You need to write new features — use a developer agent

Quick Start

Copy
# .claude/agents/debug-bot.yml
name: Expert Debug Bot
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Systematic debugging agent for root cause analysis, error tracing, and targeted bug fixes

Example invocation:

claude "Debug this error: 'TypeError: Cannot read property 'map' of undefined' in UserList.tsx:42 — it only happens when the API returns an empty response"

Core Concepts

Debugging Methodology

Phase	Activity	Tools
Reproduce	Confirm the bug exists and identify triggers	Bash (run tests), Read (check logs)
Isolate	Narrow down to the specific code path	Grep (search patterns), Read (trace code)
Analyze	Understand why the code behaves incorrectly	Read (inspect logic), Bash (run debugger)
Hypothesize	Form theories about the root cause	Analysis of gathered evidence
Fix	Implement the minimum change to fix the bug	Edit (modify code), Write (add tests)
Verify	Confirm the fix works and doesn't break anything	Bash (run tests), Read (check output)

Common Bug Categories

Data Bugs:
  ├── Null/undefined where value expected
  ├── Wrong type (string vs number)
  ├── Missing data validation
  └── Race condition on shared state

Logic Bugs:
  ├── Off-by-one errors
  ├── Wrong comparison operator
  ├── Missing edge case handling
  └── Incorrect boolean logic

Integration Bugs:
  ├── API contract mismatch
  ├── Serialization/deserialization errors
  ├── Timing/ordering issues
  └── Environment configuration differences

Configuration

Parameter	Description	Default
debug_depth	Investigation depth (surface, moderate, deep)	moderate
auto_fix	Automatically implement fixes	false
include_tests	Write regression test for the fix	true
trace_scope	How far to trace (file, module, service)	module
log_analysis	Parse and analyze log output	true

Best Practices

1. Reproduce the bug before trying to fix it. Write a failing test case or document exact reproduction steps first. Fixing a bug you can't reproduce means you can't verify the fix. If it's intermittent, increase logging to capture state when it occurs.

2. Read the error message completely, including the stack trace. The answer is usually in the error output. Stack traces show the exact execution path. Error messages often point directly to the cause. Read them carefully before diving into code.

3. Form multiple hypotheses and test each one. Don't tunnel-vision on the first theory. List 3 possible causes, design a quick test for each (add a log, change a value, comment out code), and eliminate hypotheses systematically.

4. Fix the root cause, not the symptom. Adding a null check that silences an error is a band-aid. Finding why the value is null and fixing the data flow is a cure. Band-aids accumulate into unmanageable defensive code.

5. Write a regression test before marking the fix as complete. If the bug existed without a test catching it, the test suite has a gap. Write a test that fails without your fix and passes with it. This prevents the same bug from recurring.

Common Issues

Bug only occurs in production, not locally. Environment differences cause this — different Node version, missing environment variables, different data volumes, or network conditions. Compare environment configurations systematically, check for hardcoded values that differ between environments, and add logging to narrow down where behavior diverges.

Fix for one bug introduces a new bug elsewhere. This signals tight coupling or missing test coverage. Run the full test suite after every fix, not just the tests related to the change. When a fix has wide blast radius, create the fix in a feature branch and get a code review before merging.

Intermittent bug can't be reproduced on demand. Race conditions, memory issues, and timing bugs are hard to reproduce. Add structured logging that captures relevant state, use stress testing to increase occurrence probability, and look for patterns in when it occurs (high load, specific user actions, time-based).