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, 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. ### 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. ### 7. Verify Run the reproduction again. It should now pass. Then use `verify-change` for the relevant repository checks. ## 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.