debug-with-evidence

# Debug with evidence Debug by establishing evidence before changing code. The goal is to understand the failure, not to guess until something works. ## Process ### 1. Understand the symptom Identify: - what the user expected; - what actually happened; - where it happened; - whether it is reproducible; - what changed recently when known. Do not treat nearby errors as proof of the root cause. ### 2. Build a reproduction Create the smallest reliable signal that demonstrates the exact bug. Prefer a specific, fast, repeatable signal. For intermittent failures, measure a reproduction rate across a useful number of attempts, or establish another reliable diagnostic signal when feasible. State the sample or signal used; if measurement is impractical, explain why and use the best available reproduction. Prefer, in roughly this order: - existing failing test; - focused new regression test; - CLI command; - HTTP request; - browser reproduction; - minimal local fixture; - captured logs or traces. The reproduction should fail because of the reported bug and become successful when the bug is fixed. ### 3. Gather evidence Inspect the relevant: - code path; - logs; - errors; - state; - network requests; - data; - configuration; - recent changes. Redact secrets and credentials from captured output. Prefer synthetic, anonymized, or otherwise authorized fixtures for reproducing production incidents; do not copy raw production records or credentials to local or cloud agents by default. ### 4. Form hypotheses Generate a small set of plausible causes. Rank them by evidence. For each hypothesis, define what observation would support or reject it. Avoid editing code merely to test a vague guess when a smaller diagnostic check can answer the question. ### 5. Test hypotheses Test the highest-value hypothesis first. Use instrumentation or temporary diagnostics when useful. Remove temporary debugging code before completion. Update the hypothesis ranking as evidence changes. ### 6. Fix the root cause Once evidence supports a cause: - make the smallest correct fix; - avoid unrelated cleanup; - preserve behavior outside the bug; - add a regression test when practical. When a fix fails, use what it demonstrated to update the hypothesis ranking. If attempts repeatedly fail or evidence contradicts the working hypothesis, stop editing and reassess the reproduction, failure boundary, original diagnosis, and alternatives; gather discriminating evidence before another change. Follow a clear next step when new evidence already supports one. ### 7. Verify Run the original reproduction again in a controlled environment; when meaningful, drive the changed user journey using the project's verification skill or existing harness. The original failure should now pass, and any relevant state or external effect should match expectations. Then use `verify-change` for the relevant repository checks when installed; otherwise discover and run the project's applicable checks directly, distinguishing observed passes from failures and unavailable verification. ## Rules - Reproduce before fixing when reasonably possible. - Evidence outranks intuition. - Do not hide errors with arbitrary fallbacks or broad exception handling. - Do not change several unrelated things at once to see what works. - Distinguish the root cause from symptoms. - Never expose secrets in logs, reports, or artifacts. - If reproduction is impossible, state what evidence is missing instead of pretending certainty. ## Completion Debugging is complete when: - the original symptom is understood; - the cause is supported by evidence; - the fix addresses that cause; - the original reproduction now succeeds; - relevant regression protection exists; - remaining uncertainty is reported.