Minimal repros are a fundamental tool when debugging.
What is a minimal repro?
- It is minimal. It contains the least amount of details to be sufficient. Anything that can be removed, is removed.
- It reliably reproduces the issue. "If you follow these steps exactly, you too will see the issue."
Why make a minimal repro?
🪞 For Yourself
First-and-foremost, you make repros for you.
Debugging is isolating. You cannot address what you cannot isolate. How can you fix a bug if you don’t know where it is?
If a bug is fixed in a forest without a repro, is it even fixed?
How would you know if you even fixed it? This point is profound, so let me spell it out for you:
- You have a bug
- You don’t first establish a repro.
- You try to fix the bug.
- Now what? Did you even fix the bug? How could you tell?
- Now you have to go back, undo your fix, and see if the bug comes back. In other words, you then have to go back and create a reverse-repro. You would’ve saved yourself a lot of time if you had taken a moment to first make a repro.
Fixing a bug means that the repro no longer repros.
This is similar to the maxim that you should never optimize without first measuring. If you try to make something faster without first measuring how fast it is, how will you know if you succeeded or made things worse? More importantly: how will you make sexy graphs you can brag about online?
🤝 For Others (When You Need Help)
When you ask for help with a messy, complex codebase, you’re essentially asking a mechanic to clean out your car before they can diagnose the engine. That’s your job. The isolation work is the prerequisite to getting help — not part of the help itself.
A good repro gets you:
- Faster responses — Helpers can immediately understand your problem
- Better answers — They’re solving your actual issue, not guessing
- More willing helpers — Respect for others’ time earns goodwill
People who help in forums, Discord servers, and GitHub issues are volunteering their time. Respect it.
The XY Problem: Sometimes while making a minimal repro, you’ll realize you’re asking for help with the wrong problem entirely. You thought you had a layout bug, but actually you’re overriding styles elsewhere in your codebase. Read more about the XY Problem →
🤖 For AI Tools
Minimal repros aren’t just for humans anymore.
Got ChatGPT, Claude, or Copilot? A minimal repro is perfect for pasting into an AI assistant.
The smaller and more focused your code, the better the AI can understand and help. A 2000-line file will confuse it. A 20-line reproduction will get you a precise answer.
Even better, an AI agent can iteratively try to fix the bug, see if the repro still causes the issue, in a tight feedback loop, while you go out to lunch, and you can come back to a fix that’s verified by the fact that the repro no longer repros!