dbg

/dbg

Run a structured debugging session. Four steps, strict order. No fix before reproduction. No hypothesis without evidence.

Usage

/dbg $ARGUMENTS

What I Need From You

Tell me about the problem. Any of these help:

• Error message or stack trace
• Steps to reproduce
• What changed recently
• Logs or screenshots
• Expected vs. actual behavior

Steps

1. Reproduce

Understand the problem before touching code.

• Expected vs. actual behavior — clarify what should happen and what happens instead. Get the exact error message or symptom.
• Reproduction steps — capture the steps that trigger the issue. Aim for a runnable artifact when possible: failing test, curl command, CLI invocation, log snippet.
• Scope — when did it start? Who is affected? What environment? (prod only? certain region? specific inputs? one pod or all?)

If the user isn't sure how to reproduce:

• Suggest specific places to check: logs, recent deploys, config diffs, dependency updates, error tracking dashboards, infra metrics.
• Offer a few targeted directions: "Does this happen on a fresh session?", "Does it reproduce on a different node/pod?", "What changed between when it last worked and now?", "Can you trigger it with a smaller input?"

Pin what matters: environment, timing, input shape, infrastructure state.

2. Isolate

Narrow down the component, service, or code path. Try in this order — escalate only when the prior tactic fails:

1. Attach a debugger. Use the native debugger first. One breakpoint beats ten logs.
   • Ruby: offer binding.pry or binding.irb
   • Python: breakpoint() or pdb
   • JS/TS: debugger statement + DevTools / --inspect
   • Go/Rust/C: dlv / gdb / lldb
2. Source trace + knob enumeration. Trace the code path end-to-end. List every knob: config flags, env vars, feature toggles, branch conditions, input shape, timing, concurrency. Flip one at a time.
3. In-code instrumentation. Add targeted log/print statements at the suspected fail site. Tag each probe with a unique prefix (e.g. [DBG-a4f2]) so cleanup is a single grep.

Also check: recent deploys, config changes, dependency updates, and anything that correlates with when the issue started.

3. Diagnose

Generate 2–4 ranked hypotheses. Not one. Single-hypothesis thinking anchors on the first plausible idea.

For each hypothesis:

• Does it explain the symptom end-to-end?
• What is the simplest proof? What is the cleanest disproof?
• Run the disproof first. If the hypothesis survives, it's real. If not, you saved a chase.

Cross-reference against the debug ledger (see below). Every new hypothesis must hold for all prior observations, not just the latest run. If any past run contradicts it — refine or discard.

4. Fix

• Propose a fix with clear explanation of why it works.
• Walk through side effects and edge cases.
• Suggest a test that would have caught this and will prevent regression.

Debug Ledger

Maintain a running record of every experiment in .claude/debug-sessions/{session_name}.md.

Session name: slug from the issue, e.g. auth-timeout-2026-05-21.

Format:

# Debug: {issue summary}

## Context
- **Expected**: [what should happen]
- **Actual**: [what happens instead]
- **Reproduction state**: reliable | flaky | none

## Experiment Log

| # | What changed | Result | Ruled in / out |
|---|-------------|--------|----------------|
| 1 | ... | ... | ... |
| 2 | ... | ... | ... |

## Hypotheses
1. [hypothesis] — status: testing | disproved | confirmed
2. ...

## Root Cause
[filled when confirmed. Explanation of why the bug occurs]

## Fix
[code changes or config fix applied]

## Prevention
- [test added]
- [guard added]

Update the ledger after every experiment. When stuck, read the full ledger — the answer is often in the pattern across runs.

Operating Rules

• Do not propose a fix before reproduction steps are understood. If reliable repro isn't possible, document what is known and proceed with caution.
• Do not start testing hypotheses before isolation has narrowed the fail path.
• Do not commit to a hypothesis before attempting to disprove it.
• Do not declare a hypothesis correct until the ledger confirms it against every prior run.
• If you catch yourself proposing a fix without a reproduction, stop and return to step 1.

If Connectors Available

If ~~monitoring is connected:

• Pull logs, error rates, and metrics around the time of the issue
• Show recent deploys and config changes that may correlate

If ~~source control is connected:

• Identify recent commits that touched affected code paths
• Check if the issue correlates with a specific change

If ~~project tracker is connected:

• Search for related bug reports or known issues
• Create a ticket for the fix once identified

Tips

1. Share error messages exactly — the exact text matters, don't paraphrase.
2. Mention what changed — recent deploys, dependency updates, config changes are top suspects.
3. Include context — "only in prod", "only large payloads", "started Thursday" narrows fast.