The Minimal Repro Prompt: Turn “It’s Broken” Into a Runnable Bug Report

When a bug report says “it’s broken,” you have two problems:

1) you don’t know what “broken” means (expected vs actual)
2) you can’t run the situation that produces the failure

A minimal reproduction (min repro) solves both. It’s the smallest set of code + steps that reliably triggers the bug.

The twist: creating a good min repro is a skill, and it’s easy to stall because you’re juggling context, environment details, and half-remembered steps.

So I use a simple prompt that turns a vague report into a runnable repro plan, plus an artifact (a single file, a small repo skeleton, or a CodeSandbox/StackBlitz snippet).

The Minimal Repro Prompt (copy/paste)

Paste this into your assistant after you’ve collected whatever you currently have (stack trace, screenshot, failing test, snippet, etc.).

You are my debugging partner. Your job is to help me produce a minimal reproduction of a bug.

Constraints:
- Ask me at most 5 clarifying questions.
- Do not propose fixes yet.
- The output must be runnable and minimal.

What I will provide:
- A description of the bug (expected vs actual)
- Any error messages / stack traces
- The relevant code snippet(s)
- Environment details I know (OS, runtime versions)

Your tasks:
1) Restate the bug as a single-sentence “failure contract” (Given/When/Then).
2) Identify the smallest set of inputs + steps needed to reproduce.
3) Propose a minimal repro artifact:
   - either a single file I can run
   - or a tiny project skeleton (list of files + contents)
   - or a sandbox snippet
4) Output a checklist of "remove/unnecessary" items to strip next.
5) Define a stop condition: how we know the repro is minimal.

Start by asking your clarifying questions.

Why this works: it puts your assistant into “repro mode” instead of “fix mode.” Fixes are cheap. Repros are gold.

Example: the “works on my machine” fetch bug

Let’s say a teammate reports:

“Our Node script fails on CI when calling the API. Locally it works.”

You have a stack trace that includes:

TypeError: fetch failed
cause: Error: self signed certificate

You paste the prompt + trace, and the assistant asks a few tight questions:

• Node version locally vs CI?
• Are you using global fetch (Node 18+) or node-fetch?
• Is there a proxy/mitm TLS situation in CI?
• What is the exact URL (or can we substitute one)?

Now the assistant should output something like this.

1) Failure contract

Given Node 18 on CI with corporate TLS interception, when we call fetch("https://example.internal"), then the request fails with self signed certificate.

That sentence matters because it makes the failure testable.

2) Smallest inputs + steps

• Node 18+
• A single HTTPS request
• A way to simulate a bad certificate (or a known host that triggers it)

3) Minimal repro artifact (single file)

If you can point at a public repro endpoint, great. If not, you can still build a local repro with a tiny HTTPS server using a self-signed cert.

Here’s a minimal repro you can run locally:

// repro.js
// Node 18+
import https from "https";
import fs from "fs";

// Generate certs once:
// openssl req -x509 -newkey rsa:2048 -nodes -keyout key.pem -out cert.pem -days 1 -subj "/CN=localhost"

const key = fs.readFileSync("./key.pem");
const cert = fs.readFileSync("./cert.pem");

const server = https.createServer({ key, cert }, (req, res) => {
  res.writeHead(200, { "content-type": "application/json" });
  res.end(JSON.stringify({ ok: true }));
});

server.listen(8443, async () => {
  console.log("server https://localhost:8443");

  // This is the actual repro:
  const r = await fetch("https://localhost:8443");
  console.log("status", r.status);
  console.log("body", await r.text());

  server.close();
});

Run:

node repro.js

Expected result: it fails with a certificate error. That proves your environment is enforcing TLS verification.

Then you can create a second minimal repro that shows why it “works locally” (for example: a local env var that disables cert verification, or a custom CA installed on your laptop but not CI).

4) What to remove next

• Remove any API client library: reproduce with raw fetch.
• Remove authentication: hit a local server.
• Remove unrelated config: only keep the env vars that affect TLS.
• Remove concurrency/retries: one request.

5) Stop condition (minimality)

The repro is minimal when:

• deleting any line breaks the ability to trigger the same error
• changing the URL/port is the only thing needed to run it elsewhere
• the setup instructions fit in 3 commands or fewer

A practical workflow: “strip to the bone” in three passes

The biggest mistake is trying to jump straight from “full app” to “tiny repro.” Instead, do it in passes:

1) Confirm you can reproduce at all. Don’t touch anything yet.
2) Copy into a scratch directory. Remove 50% of code. Re-test.
3) Keep cutting until it hurts. Every removal is a hypothesis test.

If you’re working with a larger project, I like to ask the assistant for a deletion plan:

Here is the directory structure. Suggest the next 10 deletions that are least likely to affect the bug. After each deletion, I will re-run the repro and report back success/failure.

This turns “min repro creation” into a boring mechanical loop — which is exactly what you want.

The Repro Pack: what to include in your final artifact

Whether you publish an issue on GitHub or send it to a teammate, a high-signal repro usually includes:

• One command to run (or two, max)
• Expected vs actual
• Exact versions (node -v, python --version, uname -a)
• A single file or tiny repo
• A note on what you already tried (not a diary, just bullets)

If you do this consistently, two things happen:

• You get fixes faster.
• You start solving half of the bugs yourself while building the repro.

That’s the quiet superpower of minimal reproductions: they force the system to confess.

---

If you want, reply with a bug report you got this week (even messy). I’ll turn it into a min repro prompt + artifact outline you can hand to a teammate.