systematic-debugging

name	systematic-debugging
description	Use when diagnosing a bug, test or build failure, performance issue, or unexpected technical behavior. Gather evidence and confirm a root-cause hypothesis before implementing a fix.

Systematic Debugging

Replace guess-and-check changes with a short evidence loop: reproduce, locate, hypothesize, test, fix, and verify.

Respect the requested scope

• If the user asks only for diagnosis, stop after establishing the cause and evidence.
• Implement a fix only when the request authorizes it.
• Do not broaden a local repair into refactoring or architecture work without a material reason and user alignment.

Workflow

1. Reproduce and bound the failure

• Read the complete error, stack trace, request, or observed behavior.
• Record the exact reproduction and expected result.
• Determine whether it is deterministic, intermittent, environment-specific, or currently unreproducible.
• Check recent code, configuration, dependency, data, and environment changes that could explain it.

If it cannot be reproduced, collect more diagnostics or identify the missing access. Do not invent a cause.

2. Locate the failing boundary

• Trace the bad value or state backward to where it first becomes wrong.
• In multi-component paths, inspect inputs and outputs at each boundary rather than jumping to the final symptom.
• Compare with the closest working path, environment, or implementation.
• Separate facts from assumptions and note evidence that rules candidates in or out.

3. Test one hypothesis

State one falsifiable hypothesis: X is the cause because evidence Y; check Z should confirm or reject it.

• Use the smallest safe experiment that changes one variable.
• Prefer read-only diagnostics before mutations.
• If rejected, keep the new evidence and form a new hypothesis; do not stack speculative fixes.
• After three failed fix attempts, stop and reassess the reproduction, assumptions, ownership boundary, and architecture before trying another patch.

4. Fix the source and verify

• Preserve a failing reproduction or regression test when practical.
• Make the smallest coherent change that addresses the confirmed cause.
• Avoid unrelated cleanup while the causal link is being tested.
• Re-run the original reproduction and relevant regression checks after the final edit.
• Use verification-before-completion before claiming the issue is fixed.

When the cause is external or intermittent

Document what was tested and why the evidence points outside the codebase. Add only the handling justified by the failure mode, such as a bounded retry, timeout, clearer error, fallback, or monitoring. Do not label a case external merely because investigation is difficult.

Output

Report four things clearly:

1. Reproduction and observed evidence
2. Confirmed cause, or the strongest remaining hypothesis
3. Change made, if authorized
4. Verification performed and remaining uncertainty