debug

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

1. State the observed symptom.
2. Reproduce it reliably.
3. Narrow the failing layer: UI, API, service, persistence, integration, environment, test harness.
4. Collect evidence: logs, stack traces, traces, screenshots, network calls, recent diffs.
5. Form 2-3 root-cause hypotheses.
6. Eliminate hypotheses with the smallest checks first.
7. Identify root cause.
8. Implement the smallest safe fix.
9. Add or update a regression test.
10. 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