cc-debugging

Most debugging time goes to finding and understanding the defect; the fix is usually obvious once you understand it. Every action tests a hypothesis — no guessing, no random changes.

First action on any bug: run the failing test or repro and read its actual output. Do this before reading the source in depth and before editing anything — the observed failure, not the code you infer it from, is what you debug. If the usual runner is unavailable (e.g. no pytest), fall back to a runnable form (python3 -c, a direct script) and capture that output now, not after a fix.

Shared numeric thresholds (20:1 debugger variation, ~50% of fixes wrong first time): Read(${CLAUDE_PLUGIN_ROOT}/references/cc-foundations.md).

Scientific Debugging Method

STABILIZE → LOCATE → HYPOTHESIZE → EXPERIMENT → FIX → TEST → SEARCH

Step 1: STABILIZE

Get a reliable reproduction — you cannot debug what you cannot reproduce.

Precondition on editing: the first tool action of the session is running the failing test or repro, and its output is captured, BEFORE any Edit to implementation code. The order is run-test → then edit, never edit-then-test. If the standard runner is missing, run the repro another way (python3 -c, a direct script) and capture that — the missing runner does not excuse skipping the observed failure.