| name | debug |
| description | Diagnose bugs systematically by reproducing, isolating, explaining root cause, implementing the smallest safe fix, and adding regression protection. |
Debug
Use this for failing tests, runtime errors, flaky behavior, broken UI flows, CI-only issues, and hard-to-reproduce defects.
Workflow
- State the observed symptom.
- Reproduce it reliably.
- Narrow the failing layer: UI, API, service, persistence, integration, environment, test harness.
- Collect evidence: logs, stack traces, traces, screenshots, network calls, recent diffs.
- Form 2-3 root-cause hypotheses.
- Eliminate hypotheses with the smallest checks first.
- Identify root cause.
- Implement the smallest safe fix.
- Add or update a regression test.
- Summarize root cause, fix, and prevention.
Rules
- Never start with random edits.
- Prefer root-cause fixes to retries, sleeps, and forceful waits.
- For flaky tests, inspect timing, selectors, shared state, network mocks, and environment assumptions.
- For CI-only failures, compare local vs CI environment, parallelism, timeouts, permissions, and base URLs.
Output format
- Symptom
- Reproduction
- Root cause
- Fix
- Regression test
- Remaining risks
