Find Bug

You are debugging a reported issue. The symptom to investigate is: $ARGUMENTS

Your goal is to find the root cause — not the first plausible explanation, and not a patch over the symptom. Work methodically through the phases below. Do not skip ahead to a fix until you can explain exactly why the bug happens.

1. Reproduce and characterize the symptom

Before touching the code, pin down what "$ARGUMENTS" actually means in concrete terms.

• Identify the exact observable failure: error message, stack trace, wrong output, crash, hang, or incorrect state.
• Determine when it happens: every time, intermittently, only with certain inputs, only in certain environments.
• Establish a reliable reproduction. If you cannot reproduce it, that is your first task — search logs, tests, and recent reports for clues.

Capture the failing signal directly when possible:

# Re-run the failing command/test and capture full output
<your test or repro command> 2>&1 | tee /tmp/find-bug.log

2. Gather evidence

Collect facts before forming theories. Read the actual error, don't paraphrase it.

• Read the full stack trace top to bottom; the deepest frame in your code is usually the most relevant.
• Grep for the error message, the failing symbol, and surrounding identifiers to locate candidate files.
• Check recent changes — a regression often points straight at the culprit.

# Find what changed recently around the suspect area
git log --oneline -20 -- <suspect_path>
git blame -L <start>,<end> <file>

3. Form hypotheses

List the plausible root causes as explicit, testable statements. Rank them by likelihood given the evidence.

Common categories to consider:

• State / lifecycle — stale cache, race condition, uninitialized or mutated shared state.
• Boundary conditions — null/empty/zero, off-by-one, overflow, timezone, encoding.
• Contract mismatch — API shape changed, wrong type, wrong units, optional treated as required.
• Environment — config, env vars, dependency version, build vs. runtime difference.

Write each hypothesis with the prediction it implies, e.g. "If the cache is stale, then clearing it before the call will make the symptom disappear."

4. Test each hypothesis

Confirm or eliminate hypotheses one at a time. Change one variable per experiment so the result is unambiguous.

• Add targeted logging or assertions at the boundary you suspect.
• Use a debugger or a minimal script to inspect actual values at the point of failure.
• Bisect when the cause is unclear and you have a known-good past state:

git bisect start
git bisect bad                 # current revision is broken
git bisect good <known_good>   # last revision known to work
# git replays commits; mark each: git bisect good | git bisect bad
git bisect reset               # when finished

5. Identify the root cause

You have found the root cause only when you can state, precisely:

• Where it is — the specific file, function, and line(s).
• Why it produces the symptom — the exact chain of cause and effect.
• When it triggers — the conditions required, which must match the reproduction from Step 1.

If your explanation does not fully account for the observed behavior (including any intermittency), you are not done — return to Step 3.

6. Report findings

Summarize concisely so the fix is obvious and safe:

• Root cause: one or two sentences naming the exact defect.
• Evidence: the experiments and observations that prove it.
• Affected scope: other call sites or inputs that hit the same defect.
• Suggested fix: the minimal change that addresses the cause, plus a test that would have caught it.

Do not apply the fix unless asked — your job here is to locate and explain the root cause. Hand off a clear, verifiable diagnosis.