Repro

Repro

A bug you can't reproduce is a rumor. Your job is to turn the rumor into the smallest runnable artifact that makes the bug happen on demand — because that artifact is 80% of the fix, it's the regression test, and it's the difference between "closed: can't reproduce" and closed.

Phase 1 — Interrogate the report (and the code)

Extract every concrete fact from the report: exact error text, the feature/action involved, timing ("sometimes", "after a while", "since the update"), environment hints. Then interrogate the codebase, which usually knows more than the reporter:

• Search for the error message → the throwing site → walk backwards to every path that can reach it.
• For each path, ask what input or state makes it fire. Each answer is a hypothesis.
• Mine the vague words: "sometimes" → concurrency, ordering, randomness, time; "on some inputs" → boundaries, encoding, size; "after a while" → accumulation, leaks, expiry, overflow; "since the update" → diff the update (and consider handing that part to a bisect).

Rank hypotheses by likelihood × ease of testing.

Phase 2 — Hunt

Build a harness that invokes the suspected code path directly — not the whole app — and try hypotheses in ranked order. Escalate only as needed:

• Deterministic candidates first: boundary inputs, malformed data, empty/huge/unicode.
• Then stateful ones: specific sequences, repeated calls, accumulated state.
• Then nondeterministic ones: tight loops for races, controlled seeds for randomness, frozen/advanced clocks for time bugs. For intermittents, crank the trigger conditions (parallelism, iteration count) until failure is reliable, then record the exact recipe.
• Instrument when hypotheses run out: assertions and logging at the suspect path to catch the state at failure time, then work backwards from the caught state.

First trigger is not the finish line — a repro that fires 1-in-20 is a lead, not a deliverable. Keep tightening until it fires every run (or document the honest rate and the conditions that maximize it).

Phase 3 — Minimize

Delta-debug the trigger down: remove every line, dependency, config flag, and data field that isn't needed for the bug to fire, re-running after each removal. The end state is the smallest input and shortest script that still reproduces — small enough to paste into an issue, obvious enough that the root cause is often visible in the repro itself.

Phase 4 — Deliver

1. The repro script — runnable with one command, self-contained, seeded/deterministic wherever possible.
2. REPRO.md — exact trigger conditions, expected vs. actual, failure rate if not 100%, environment requirements, and the root-cause pointer if the minimization exposed it (it usually does).
3. The regression test — the repro converted into the project's test framework, currently failing, ready to flip green with the fix.

If it won't reproduce

That's a report, not a failure: document every hypothesis tested and ruled out, the harnesses used, and what evidence from the reporter would discriminate between surviving hypotheses (exact version, the input file, a log with timestamps). Ruling out ten causes is progress, and the discriminating-evidence list turns "can't reproduce" into a specific, answerable ask.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tokyubevoxelverse
• Source: tokyubevoxelverse/repro
• License: MIT

Install and usage instructions live in the source repository linked above.