Debug

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