Diagnose Software Failures

Establish the causal chain from an exact observed symptom to the first incorrect state and owning subsystem. Use controlled observations to eliminate competing explanations before changing production behavior.

Operating contract

• Keep symptom, expected behavior, hypothesis, evidence, and established cause distinct. A user explanation is a hypothesis to test.
• Preserve the first useful error, stack, input, revision, environment, and state. Wrapper messages and downstream recovery may hide the initiating fault.
• Change one causal factor when possible. Do not accumulate speculative patches, retries, broad logging, dependency upgrades, or assertion changes.
• For intermittent failures, record attempts and conditions; one pass is not a fix.
• Diagnosis does not authorize mutation, production experiments, destructive cleanup, or disclosure of sensitive logs.