Durga

Durga — Slayer of Demons (Debugging)

Durga governs the hunt: find the demon, understand it, kill it, and make sure it stays dead.

Reproduce first

• No fix without a reproduction. Reduce it to the minimal repro: smallest input, fewest steps, ideally a failing test.
• If you can't reproduce it, gather evidence instead: logs, stack trace, request ID, environment, timestamp. "Works on my machine" means the environments differ — find the difference.
• Pin down flakiness before debugging: run the repro 10 times. Intermittent failures are still deterministic given the right conditions (timing, ordering, state).

Read the error

• Read the actual error message, completely, including the last line of the traceback. Most bugs are named in the message.
• Read the first error, not the last — cascading failures bury the root cause under noise.
• Search the exact error string in the codebase before searching the web.

Narrow the cause

• Check recent changes first: git log --oneline -20, last deploy, last dependency bump, last prompt change. Most bugs are new bugs.
• Binary-search the cause: git bisect across commits; comment out / stub out halves of the code path; halve the input until the failure disappears.
• One hypothesis at a time. State it ("the cache returns stale rows"), design the cheapest test that could falsify it, run it, then move on. Never change two things per experiment.
• Rubber-duck in writing: three sentences — what I expected, what happened, what I've ruled out. Half the time this reveals the answer.

Fix it properly

• Never fix what you can't explain. A change that "makes it go away" without a causal story is a second bug waiting.
• Every fixed bug gets a regression test that fails on the old code and passes on the new (see agni). Ship fix and test in the same PR.
• After fixing, ask: where else does this pattern exist? Kill the whole class, not one instance.

AI-native specifics

• Log the full prompt, response, model ID, and parameters for every failed LLM call — you cannot debug what you didn't capture. Redact PII in logs, not detail.
• Distinguish model nondeterminism from code bugs: pin temperature=0 (and seed where supported) while debugging. If the failure persists at temperature 0, it's your code or prompt; if it vanishes, it's variance — handle it with validation and retries, not prompt tweaks.
• Reproduce LLM failures from the logged prompt verbatim, outside the app, before touching application code.
• Provider outages and silent model updates are real causes — check status pages and pin model versions (gpt-4o-2024-08-06, not gpt-4o).

Before closing the bug — checklist

• Root cause explained in one sentence, with evidence
• Minimal repro existed before the fix
• Regression test added and failing on the old code
• Same pattern searched for elsewhere in the codebase
• For LLM bugs: prompt+response captured, nondeterminism ruled out