Bug Repro Builder

---
name: bug-repro-builder
description: Use when building a minimal reproducible example for a bug report or flaky test. Triggers on "minimal repro", "MRE", "bug report", "isolate this bug", or pasted stack traces with a request for narrowing.
---

# Bug Repro Builder

The bug report you'd want to receive is one where you can reproduce the issue in 60 seconds with copy-paste. That's the bar. Anything noisier is a guessing game for the maintainer.

## Required inputs

1. **The observed failure** — error message, stack trace, wrong output, hang
2. **The code or environment** that produces it
3. **What you expected** instead
4. **Frequency** — always, sometimes (X%), only on Y machine
5. **Environment** — versions, OS, runtime, package manager

If the user has a stack trace but no idea what triggers it, ask: "What were you doing when this happened? What input?" A repro starts from a triggering action, not a symptom.

## Reduction process (in order)

### 1. Confirm reproduction
Before reducing, confirm you can reproduce reliably. If frequency is "sometimes," establish what makes it reliable (specific input, specific timing, specific load). A repro that fails to fail is useless.

### 2. Strip dependencies
Remove every package, file, and config NOT needed to trigger the bug. Common cuts:
- Auth, sessions, middleware → remove
- ORMs and abstractions → drop to the underlying call when possible
- Test framework boilerplate → reduce to a script if simpler

### 3. Strip data
Reduce input to the smallest that triggers the bug:
- 10,000-row CSV → can you reproduce with 2 rows? 1?
- Long string → which character/byte/sequence is load-bearing?
- Complex object → which field, set to which value?

### 4. Strip code
- Inline helpers
- Remove unused branches
- Replace business logic with the simplest expression that still triggers the bug

### 5. Confirm reduction still reproduces
Every reduction step must be re-tested. If the bug stops reproducing, the last thing you removed was load-bearing — put it back.

## Output structure

```
## Summary
1 sentence. "calling fn(X) returns Y instead of Z."

## Environment
- Runtime: Node 22.4.0
- OS: macOS 14.5
- Package: foo@1.2.3
- Reproduction rate: 100% / 30% / etc.

## Reproduction (minimal)

\`\`\`<lang>
[the smallest possible runnable example]
\`\`\`

Run with: \`exact command\`

## Expected
What should happen — 1 sentence.

## Actual
What happens — paste the actual error / output / stack trace.

## Notes
- What I tried that did NOT change behavior (rules out red herrings)
- Where I think the bug lives (if I have a hypothesis), but DO NOT confuse with confirmed cause
```

## Anti-patterns

- 200-line repro that imports your whole app — maintainer won't bother
- "Sometimes it fails" with no triggering pattern — not a repro, a vibe
- Stack trace without a way to reproduce — you have a symptom, not a bug report
- Mixing multiple bugs into one report — split them
- Including a fix attempt in the bug report — file the fix as a separate PR

## When the bug is in YOUR code

The same process works internally. A debugger / colleague helping you needs the same minimal context. "I have a function that fails on this input — here's the smallest version that fails" is exactly the right framing for pair-debugging.

## Tone

- Factual, not narrative. "Calling `X` returns `null`." Not "I'm trying to do Y and it doesn't work."
- Specific. Versions, exact commands, exact inputs.
- Honest about what you don't know — "Bug seems to involve timing; haven't confirmed."

## Output

Markdown. Code blocks for repro and trace. Headers exactly as above so any maintainer can scan it.