Systematic Debugging: Agent Skill (SKILL.md) for Claude Code, Codex and Cursor

Hunts down bugs whose cause isn't obvious: flaky or intermittent failures, 'works locally but fails in CI', regressions nobody can place, or a fix that didn't stick.

Prompt

Installs to .agents/skills/systematic-debugging-agent-skill-skill-md-for-claude-code-codex/

mkdir -p .agents/skills/systematic-debugging-agent-skill-skill-md-for-claude-code-codex && curl -sL "https://prompts-gpt.com/prompts/systematic-debugging-agent-skill-skill-md-for-claude-code-codex-and-cursor/raw" -o .agents/skills/systematic-debugging-agent-skill-skill-md-for-claude-code-codex/SKILL.md
SKILL.md
Preview
---
name: systematic-debugging-agent-skill-skill-md-for-claude-code-codex
description: "Hunts down bugs whose cause isn't obvious: flaky or intermittent failures, 'works locally but fails in CI', regressions nobody can place, or a fix that didn't stick."
---

# Systematic Debugging: Agent Skill (SKILL.md) for Claude Code, Codex and Cursor

Hunts down bugs whose cause isn't obvious: flaky or intermittent failures, 'works locally but fails in CI', regressions nobody can place, or a fix that didn't stick.

## Prompt

```
---
name: systematic-debugging
description: "Hunts down bugs whose cause isn't obvious: flaky or intermittent failures, 'works locally but fails in CI', regressions nobody can place, or a fix that didn't stick. Makes the bug reproduce reliably, ranks hypotheses, narrows with git bisect or input halving, confirms the cause before changing code, and proves the fix with a regression test. Use when a test is flaky, it 'works on my machine', something broke after an upgrade or merge, a first fix didn't work, or when asked to find the root cause."
---

# Systematic debugging

For bugs where the cause isn't obvious. If the error message already points at the faulty line, write a failing test, fix it and skip the rest of this.

## Steps

1. Write down observed vs expected, the exact error text, and the exact command, request or click path that shows it.
2. Make it reproduce reliably.
   - Intermittent: run the failing test 20 times in a loop and record how many runs fail. Run it alone, then with the full suite, then in a different order, to expose shared state between tests.
   - Works locally, fails in CI (or the reverse): list the differences and check each one: runtime and dependency versions (is the lockfile used?), env vars, time zone and locale, OS and filesystem case sensitivity, CPU count and test parallelism, network access, seed data and secrets. Copy CI's setup locally (same versions, TZ=UTC, the same env vars) until it fails here too.
   - Can't reproduce at all: ask for logs, versions, the exact input and steps. Don't guess a fix.
3. Shrink: cut the input and steps down to the smallest case that still fails.
4. Hypothesize: list two to four possible causes, ranked by likelihood, each with the evidence for it and the check that would rule it out.
5. Narrow, one check at a time, recording each result:
   - Regression with a known-good commit: `git bisect start <bad> <good>`, then `git bisect run <test command>` (the command must exit non-zero when the bug is present), then `git bisect reset`.
   - Large input or config: halve it and keep the half that still fails.
   - Otherwise: add targeted logging or inspect values in a debugger at the point the hypothesis predicts.
6. Confirm the cause: you have it when you can explain the full chain from cause to symptom and predict a change that makes the bug go away.
7. Write a regression test that fails on the current code every time. For flaky bugs, control the cause in the test (fixed clock, seeded randomness, forced ordering) so it fails reliably. Run it and watch it fail.
8. Fix the root cause, not the symptom. A try/catch, a null check, a longer timeout or a retry that hides the error is not a fix unless the cause really is an expected condition.
9. Verify: the regression test passes, the full suite passes, the original reproduction no longer fails. For an intermittent bug, rerun the loop with several times as many runs as it took to fail before. Remove temporary logging.
10. Report: symptom, root cause, how you found it, the fix, the test added, and the command output that shows it passing.

## Rules

- No fix before a confirmed cause.
- Change one thing at a time.
- After three hypotheses fail, stop guessing and re-gather data: reread the error, and check your assumptions about versions, environment, config and inputs.
- Never say "fixed" without command output that shows it.
- If the root cause is out of scope (a library bug, infrastructure), say so, apply a clearly labeled workaround, and note what the real fix would be.

## Example output

```
Symptom: checkout.test.ts fails in CI 1 run in 6; never locally.
Cause: test relies on local time; CI runs in UTC, so "today" flips at 00:00 UTC. Found by running locally with TZ=UTC (fails 20/20 between 00:00 and 01:00 local).
Fix: compare dates in UTC in isExpired().
Test: "treats a coupon ending today as valid in any time zone" with a fixed clock; failed before, passes now.
Verified: 100 loop runs, 0 failures; full suite 212 passed.
```
```

## Usage Notes

Save as .claude/skills/systematic-debugging/SKILL.md in one project (or ~/.claude/skills/systematic-debugging/ for all of them); Codex reads .agents/skills/systematic-debugging/SKILL.md. Then ask for the job in plain words and the agent loads it. Or install with: npx skills add prompts-gpt/skills --skill systematic-debugging.

Example output

At a glanceFailures per 20 runs by test setupRandom order, not parallelism, triggered the failure; the shrunk pair failed every time.
  • Alone, locally: 0/20
  • Full suite, -n auto: 0/20
  • -n 2 with random order: 7/20
  • -n 0 with random order: 6/20
  • EUR test then bulk discount: 20/20
  • Same pair, reverse order: 0/20

Example for: a Python FastAPI service where test_order_totals.py::test_bulk_discount fails intermittently in GitHub Actions after a dependency bump; the first "fix" (a retry decorator) didn't stick.

Debugging log: test_bulk_discount intermittent failure

1. Observed vs expected

  • Expected: assert total == Decimal("184.50")
  • Observed (CI only): AssertionError: Decimal('184.49') != Decimal('184.50')
  • Command: pytest tests/test_order_totals.py -p xdist -n auto

2. Reproduction

  • Alone, 20 runs locally: 0/20 fail.
  • Full suite, -n auto (CI uses 2 workers, laptop uses 10): 0/20.
  • -n 2 -p randomly: 7/20 fail.
  • -n 0 with random order: 6/20. Parallelism ruled out. Order is the trigger.

3. Shrink
The smallest failing pair is test_currency_format.py::test_eur_rounding followed by test_bulk_discount. It fails 20/20 in that order and 0/20 in reverse.

4. Hypotheses (ranked)

#CauseEvidenceRule-out check
1Global decimal context mutatedOff by one cent looks like a rounding changePrint getcontext().rounding at the start of the test
2Cached price fixture mutatedFixture scope is sessionDeep-copy the fixture and rerun
3babel 2.15 bump changed roundingBump landed the same weekPin 2.14 and rerun

5. Narrowing

  • H1: getcontext().rounding printed ROUND_HALF_EVEN after the EUR test and ROUND_HALF_UP when the test ran alone. Confirmed.
  • git bisect run pytest tests/test_currency_format.py tests/test_bulk_discount.py -p no:randomly → first bad commit a3f91c2 ("format EUR per banker's rounding"). It sets getcontext().rounding globally inside format_eur().

6. Cause chain

  1. format_eur() mutates the thread-global decimal context.
  2. That leaks into the later apply_bulk_discount(), so 184.495 rounds half-even to 184.49.
  3. CI's random ordering puts the EUR test first about 1 run in 3. A developer's default ordering never does.

7. Regression test
test_bulk_discount_unaffected_by_prior_formatting calls format_eur(Decimal("1.005")), then asserts the discount total is 184.50. On current code it failed 20/20.

8. Fix

  • format_eur() now uses with localcontext() as ctx: ctx.rounding = ROUND_HALF_EVEN.
  • apply_bulk_discount() now passes rounding=ROUND_HALF_UP explicitly to quantize.
  • Removed the @retry(3) decorator. It only hid the failure.

9. Verification

$ for i in $(seq 1 150); do pytest -n 2 -p randomly -q || echo FAIL; done | grep -c FAIL
0
$ pytest -q
487 passed in 41.2s

The temporary getcontext() prints have been removed.

10. Report

Symptom: test_bulk_discount fails ~1 in 3 CI runs; never locally.
Cause: format_eur() set the global decimal rounding to HALF_EVEN, which leaked into later tests. Exposed by CI's random test order.
Found by: order-controlled loop runs, test-pair shrink, then git bisect → a3f91c2.
Fix: localcontext() in format_eur(); explicit rounding in apply_bulk_discount(); removed the masking retry.
Test: test_bulk_discount_unaffected_by_prior_formatting. Failed 20/20 before the fix, passes now.
Verified: 150 randomized runs, 0 failures; full suite 487 passed.
Written by AI from this prompt. Your results will vary.

Save as .claude/skills/systematic-debugging/SKILL.md in one project (or ~/.claude/skills/systematic-debugging/ for all of them); Codex reads .agents/skills/systematic-debugging/SKILL.md. Then ask for the job in plain words and the agent loads it. Or install with: npx skills add prompts-gpt/skills --skill systematic-debugging.

Make it repeatable

Keep using this prompt without pasting it in every time.

Prompt details

By
Prompts-GPT editors
Published
How prompts are written and checked

Did this prompt work?

Keep exploring

More in AI Coding Agents