---
name: flaky-test-hunter
description: "Finds out why a test passes sometimes and fails others, checking timing, shared state, ordering and environment, then fixes the cause instead of adding retries. Use when a test fails intermittently, passes on rerun, or fails only on CI or only in the full suite and the team wants the cause found. Do not use for a test that fails every time or choosing a testing strategy. Related topics: coding, technical."
---

# Flaky Test Hunter

Finds out why a test passes sometimes and fails others, checking timing, shared state, ordering and environment, then fixes the cause instead of adding retries.

## When to use

Use this skill when a test fails intermittently, passes on rerun, or fails only on CI or only in the full suite and the team wants the cause found. Do not use it for a test that fails every time or choosing a testing strategy.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Read the failing and passing output side by side and note every difference in order, timing or data.
3. Score the four buckets of timing, shared state, order and environment against that evidence and rank them.
4. Give a confirming command for the top suspects, such as repeated runs, isolation, a fixed seed or reversed order.
5. Name the most likely root cause and justify it from the evidence rather than from habit.
6. Write the fix that removes the cause, and show how to rerun enough times to trust the result.

## Inputs

- **Test name and code** (longer free text)
- **Failure output** (longer free text)
- **How often it fails** (free text, e.g. "1 in 10 locally or 1 in 3 on CI")
- **Where it fails** (choose one: Only on CI, Only locally, Both, Unknown)
- **Test framework and runner** (free text, e.g. "Jest or pytest or Playwright")
- **Recent changes** (longer free text)

## Output

A ranked suspect table with evidence for and against each, the commands to confirm them, the named root cause, the code fix, and a rerun plan with a pass threshold.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Flaky Test Hunter

Find the real cause of a flaky test and fix it.

- Test name and code: {{Test name and code}}
- Failure output: {{Failure output}}
- How often it fails: {{How often it fails}}
- Where it fails: {{Where it fails}}
- Test framework and runner: {{Test framework and runner}}
- Recent changes: {{Recent changes}}

Sort suspects into four buckets and test each in order. Timing: sleeps, unawaited promises, animations, timeouts, clocks and time zones. Shared state: globals, database rows, files, caches and singletons left by earlier tests. Order and parallelism: does it pass alone but fail in the suite, or fail when run in a different order or with other workers. Environment: CPU speed, network, random seeds, locale, resource limits and version drift. For each bucket say what evidence in the output points toward or away from it, and give a command that would confirm it, such as running 50 times, running in isolation, or fixing the seed. Name the most likely cause, then give the fix at the root: wait on a condition rather than a delay, isolate state, or control the clock. Reject retries and longer timeouts unless nothing else is possible, and say so.

## Pitfalls

- Adding a retry or a longer sleep, which hides the flake and slows the suite while the cause stays.
- Blaming CI slowness without checking for leaked state from an earlier test, the more common cause.
- Declaring victory after a few green runs, when a 1 in 20 flake needs dozens of runs to show it is gone.