| name | debugging-discipline |
| description | Debug systematically instead of guessing. Use when fixing bugs, failing tests, flaky behavior, runtime errors, regressions, or unexpected output. Guides reproduction, isolation, hypotheses, evidence, one-variable changes, root cause, and regression tests. |
Debugging Discipline
Use this skill for bug-fix tasks and failing verification.
Workflow
- Reproduce or precisely describe the failure.
- Capture the expected behavior and actual behavior.
- Identify the smallest failing path or input.
- Form one hypothesis from evidence.
- Inspect code/data/logs that can confirm or reject the hypothesis.
- Change one variable at a time.
- Fix root cause, not just the visible symptom.
- Add a regression test or equivalent guard.
- Re-run the failing check and relevant adjacent checks.
Evidence to collect
- failing assertion or error
- inputs and state
- recent changes
- boundary/edge conditions
- logs with sensitive data redacted
- dependency/environment differences
Avoid
- Random edits before reproduction.
- Explaining away failures without evidence.
- Masking errors by broad catch/ignore logic.
- Declaring fixed without rerunning the failing path.
