Debugging & Root-Cause Analysis

Here is the error and the relevant code. Give me three hypotheses ranked by likelihood, and the single observation that would confirm or kill each one.

Why it worksHypotheses with falsification tests beat a confident guess.

Do not propose a fix yet. First tell me what you would need to see to be certain of the cause.

Why it worksSeparates diagnosis from treatment, which is where most debugging goes wrong.

This bug is intermittent: [description]. What conditions would make it appear only sometimes? List the environmental and timing factors.

Why it worksIntermittent bugs are usually concurrency, ordering, or environment; naming them narrows the search.

Walk the execution path for [input] through this code and tell me at which line the actual behavior first diverges from the expected behavior.

Why it worksFinds the first divergence rather than the last symptom.

Here is the stack trace: [trace]. Explain each frame in plain language and tell me which frame is the culprit versus which is collateral.

Why it worksDistinguishes the origin of the fault from the place it surfaced.

What changed recently that could cause this? Here is the diff: [diff]. Rank the changes by suspicion and say why.

Why it worksRecent changes are the highest-prior cause; ranking them saves hours.

Write the minimal reproduction for this bug. Strip everything that is not necessary to trigger it.

Why it worksA minimal repro is both the proof of understanding and the regression test.

Is this a bug in our code, our configuration, our dependency, or our assumptions? Give me the evidence for each possibility.

Why it worksPrevents days lost fixing the wrong layer.

Explain this behavior as if it were correct. What would have to be true for this to be the intended outcome?

Why it worksSteelmanning the bug often reveals a wrong assumption upstream.

Here is the log output around the failure: [logs]. Reconstruct the timeline and identify the first anomaly, not the loudest one.

Why it worksThe first anomaly is the cause; the loudest is usually the consequence.

What state would have to be corrupted for this symptom to appear? Trace back to where that state is written.

Why it worksWorks backwards from symptom to the write that caused it.

Propose the instrumentation that would make this bug obvious next time, and tell me what it would have shown today.

Why it worksTurns a one-off investigation into permanent observability.

This works locally and fails in production. List every environmental difference that could matter, ordered by likelihood.

Why it worksSystematically enumerates the local/prod gap instead of guessing.

Here is the failing test: [test]. Is the test wrong, the code wrong, or the requirement wrong? Argue each case.

Why it worksThree-way diagnosis prevents "fixing" the test to make the code pass.

Given this race condition: [description]. Show me the interleaving that produces the failure, step by step.

Why it worksAn explicit interleaving is proof; a vague "it's a race" is not.

What is the smallest change that would have prevented this bug, and what class of bug does it prevent in the future?

Why it worksFixes the class, not just the instance.

Write the postmortem skeleton for this incident: timeline, impact, root cause, contributing factors, detection gap, action items.

Why it worksBlameless structure that produces action items instead of a narrative.

Here is the fix I am considering: [fix]. Tell me what else it might break and what test would catch that.

Why it worksEvery fix is a change; this checks the blast radius before you ship it.

Why did our tests not catch this? Identify the gap in coverage and the specific test that should exist.

Why it worksConverts a production bug into a permanent test.

Summarize this debugging session as a runbook entry: symptom, diagnosis steps, root cause, fix, and how to recognize it next time.

Why it worksTurns tribal knowledge into a document the next on-call engineer can use.

Here is the bug report: [report]. Tell me what information is missing that would let me reproduce it, and write the questions I should send back.

Why it worksMost "unreproducible" bugs are under-specified reports, not mysteries.

This failure only happens under load: [description]. Walk me through the resource that saturates first and the queue that backs up behind it.

Why it worksLoad failures are resource exhaustion; naming the resource ends the guessing.

Here is the memory profile: [data]. Is this a leak, a spike, or expected retention? Show me the evidence for each and what would distinguish them.

Why it worksDistinguishes three problems that look identical on a graph and have different fixes.

Trace this data corruption backwards: [symptom]. At which write did the value first become wrong, and what allowed that write?

Why it worksCorruption is always introduced at a write; finding it beats patching the read.

Here is the timeout: [context]. Is the cause latency, a deadlock, a retry storm, or a downstream dependency? Give me the observation that separates them.

Why it worksFour causes, four fixes; the observation is what stops you applying the wrong one.

This bug appears only in one environment or one tenant: [description]. What is different about that path, and how would I prove it?

Why it worksScoped failures point at configuration or data, not logic.

Here is the code path and the input that triggers it: [context]. What is the smallest input that still triggers it, and what is the boundary value where it stops?

Why it worksBoundary hunting turns a vague failure into a precise condition.

Assume the bug is in the code we trust most. What would that look like, and how would we rule it out?

Why it worksThe trusted component is the one nobody instruments; that is where the surprise lives.

Here is the retry logic: [code]. Show me how it behaves when the downstream is slow rather than down, and where it amplifies the outage.

Why it worksRetries turn a degradation into an outage; slow is the case nobody tests.

Here is the error handling: [code]. Which failures are being swallowed, and what would we see in production if this path were failing silently?

Why it worksSilent failures are the ones that surface as data loss weeks later.

Given this symptom: [symptom]. What is the cheapest experiment that would halve the space of possible causes?

Why it worksDebugging is search; bisecting the hypothesis space beats reading code harder.

Here is the fix: [fix]. Write the test that fails before it and passes after, and tell me what it does not cover.

Why it worksA fix without a failing-first test is a fix you cannot prove.

This bug was fixed once before and came back: [history]. What does the regression tell us about the real cause?

Why it worksA recurring bug means the first fix treated a symptom.

Here is the distributed trace: [trace]. Which service added the latency, and was it the service or the call it made?

Why it worksSeparates self-time from wait-time, which is where distributed debugging usually stalls.

Here is the state machine: [description]. Enumerate the transitions that should be impossible and check whether the code can reach them.

Why it worksImpossible states reached in production are always a missing guard.

Given this incident: [description]. What was the detection gap, the response gap, and the recovery gap — and which one cost the most minutes?

Why it worksSplits incident cost into three measurable parts instead of one vague duration.

Here is the dependency version change: [diff]. Which behavior change in the changelog could produce this symptom?

Why it worksUpgrades break on undocumented behavior, not on the headline features.

What would a senior engineer check first that a junior engineer would not, for this symptom: [symptom]?

Why it worksEncodes the diagnostic instinct that usually takes a decade to build.

Here is the failing scenario: [scenario]. Write the assertion that captures the correct behavior, then tell me the minimal code change that satisfies it.

Why it worksAnchors the fix to a stated expectation rather than to the current output.

Summarize this bug as a one-line invariant that was violated, then tell me where else in the codebase that invariant is assumed.

Why it worksOne root cause usually has several other places waiting to fail the same way.