wiki / coding-intermittent-bug-diagnosis / edit

Suggest an edit.

Improvements are reviewed before going live, like any wiki.

Title

One-line summary

The prompt

I have a bug that does not reproduce reliably, so trial-and-error fixes are off the table. Run this as a differential diagnosis and design instrumentation to catch it.

Symptom: [WHAT GOES WRONG, HOW OFTEN, AND WHAT NORMAL LOOKS LIKE]
Occurrence pattern: [WHEN IT HAPPENS — TIME OF DAY, LOAD, SPECIFIC USERS OR INPUTS, AFTER DEPLOYS — OR "NO PATTERN FOUND"]
What I have already tried: [ATTEMPTS AND RESULTS, OR "NOTHING YET"]
System shape: [LANGUAGE/RUNTIME, CONCURRENCY MODEL, RELEVANT ARCHITECTURE — QUEUES, CACHES, RETRIES, TIMEOUTS]
Evidence: [PASTE LOGS, STACK TRACES, METRICS, RELEVANT CODE]

Produce:

1. Fact list: everything the evidence establishes, each item tagged with its source. Separately, list plausible-sounding assumptions I may be making that are not actually established — intermittent bugs hide in that gap.

2. Candidate mechanisms: enumerate concrete failure mechanisms consistent with the facts — races on specific shared state you can name, cache staleness, retry duplication, clock or timezone edges, resource exhaustion, unhandled partial failure. For each: the exact sequence of events that produces the symptom, what the occurrence pattern would look like if this were the cause, and whether that matches mine.

3. Instrumentation plan: since I cannot reproduce on demand, specify what to record so the next occurrence is diagnostic — exact log lines with the variables to include, correlation IDs to thread through, counters or timestamps to add. For each item, state which candidate mechanism it confirms or eliminates. Prefer cheap, safe-to-ship instrumentation over invasive changes.

4. Falsifiable predictions: for the top two candidates, state something observable that must be true in the next occurrence if that candidate is the cause. If a prediction fails when I report back, the candidate is out — say so explicitly.

Do not propose a fix yet. A fix for an undiagnosed intermittent bug just moves the mystery. Once the instrumentation identifies the mechanism, we fix it then.

Write it so someone can paste it straight into Claude, ChatGPT or Gemini and fill the [BRACKETS].