Debug With Evidence

Debug with Evidence

Find and prove the root cause before changing behavior. A disappearing symptom is not sufficient evidence of a correct fix.

Workflow

1. Define the failure.

• Record observed behavior, expected behavior, exact inputs, environment, frequency, timeline, and recent relevant changes.
• Separate reported facts from assumptions.

1. Establish a reliable reproduction.

• Reproduce with the smallest safe case available.
• Preserve the failing command, request, data shape, or user steps.
• If reproduction is impossible, identify the missing evidence instead of guessing.

1. Trace the relevant code path.

• Inspect applicable instructions, entry points, state transitions, dependencies, error handling, and existing tests.

1. Form ranked hypotheses.

• Make each hypothesis specific and falsifiable.
• State the observation that would support or reject it.

1. Collect targeted evidence.

• Use existing logs, stack traces, test output, browser state, query plans, profiles, metrics, or version history.
• Add minimal temporary instrumentation at suspected boundaries when needed.
• Change one investigative variable at a time.

1. Identify the root cause.

• Explain the causal chain from triggering condition to observed failure.
• Show why the evidence favors it over competing hypotheses.
• Reject symptom-masking fixes such as an unexplained null check or broad retry.

1. Lock a regression test.

• Add the smallest test that reproduces the bug and confirm it fails for the proven reason before applying the fix.
• Use the lock-tests-first skill when the contract requires broader coverage.

1. Apply a targeted fix.

• Correct the cause with the smallest coherent change.
• Preserve unrelated behavior and remove temporary instrumentation unless it provides lasting observability value.

1. Verify.

• Re-run the reproduction and regression test, then relevant surrounding checks.
• Test boundary and failure cases suggested by the root cause.
• Explain why the fix prevents recurrence rather than hiding the symptom.

Output

Provide the reproduction, evidence, root cause, rejected hypotheses, fix, regression protection, verification results, and residual uncertainty. Never claim a cause solely because a patch made the immediate error disappear.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: himanshi-28
• Source: himanshi-28/coding-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.