Debugging by Evidence

Core principle. Test the claim needed for the decision, not every unknown in the incident.

• A hypothesis chooses an experiment; it is not a confirmed cause. Reports, logs and code can supply falsifiable hypotheses before a local reproduction.
• Use complementary layers of evidence. An incident record shows occurrence; a controlled experiment can show defective handling without identifying the original trigger.
• You opened this in the middle of something. This is how to do that work, not a replacement for it. Name what you were doing before you start, and return to it when this is done.

Choose a signal for the question

• Start with the reported failure and available evidence. A local passing run does not erase a recorded incident.
• Choose reproduction, replay, controlled fault injection or tracing by what each can establish. They are alternatives, not a mandatory ladder.
• Keep the handling under test real. Inject a justified dependency outcome or schedule, then assert the caller-visible contract.
• Record the command, conditions and result. Label injected conditions; do not report them as observed production events.

What you may write, and when

• Before a supported repair, writes are limited to authorised diagnostic tests and instrumentation. Controlled changes to inputs, dependency outcomes or scheduling are experiments, not production fixes.
• Preserve the baseline. Change the condition under investigation, not the handling whose correctness you are testing. Isolate substitutions and retain the original evidence.
• The licence stops at the workspace boundary. No commit, branch move, remote action or deployment. Remove temporary instrumentation; retain useful regression tests.