troubleshoot

Start by reproducing the failure, then state one likely root cause and a targeted check to confirm or reject it. Test one hypothesis at a time, write a failing test that reproduces the root cause, and apply the smallest safe fix only after evidence confirms it.

After three rejected hypotheses, stop generating new ones and trace the data flow from the entry point instead. This shifts debugging from speculation to direct observation of how data actually moves through the system.

Yes, flaky behavior is an explicit use case. The workflow requires reproducing the failure with evidence before fixing, and verification demands the strongest relevant checks pass, which exposes timing and isolation issues.

Speculative changes, debug prints, and dead code accumulate when fixes are not audited. The cleanup guide mandates auditing the task's own git diff for debug output, unused imports, orphan files, and commented-out code before persisting.

It requires an actionable symptom such as an error, trace, or failing command; without one, the process halts and asks for clarification. It also forbids editing build configuration or suppressing linter diagnostics, so environment-level issues may be out of scope.