Turn a Vague Bug Report into Evidence a Maintainer Can Rerun

williamgritti — Fri, 11 Sep 2026 09:36:46 +0000

“It breaks sometimes on Windows” may describe a real defect, but it does not give a maintainer a testable starting point. The useful transformation is small: turn the report into one trigger, one command, one literal expected result, and one captured actual result.

This article shows a compact workflow that works with a human maintainer or a coding agent. It does not require uploading source code or diagnostic data to a third-party service.

1. Write the failing contract first

Start with facts that another person can rerun:

Trigger: one synthetic input
Command: node repro.mjs
Expected: literal value and exit 0
Actual: sanitized output and exit 1
Frequency: 3 failures in 3 clean runs

Avoid “works correctly” and “throws an error.” Record the exact value or exception. If the symptom is intermittent, state the number of attempts and failures.

2. Remove everything the failure does not need

A minimal reproduction should have one reason to fail. Remove unrelated dependencies, UI, network calls, credentials, production data, and setup steps. Keep a negative control when it helps distinguish the suspected boundary:

input A -> observed failure
input B -> success
only one relevant condition differs

If removing a component makes the symptom disappear, record that result. It narrows the investigation even when you cannot yet explain the cause.

3. Capture a small environment block

Include the runtime version, operating-system family, CPU architecture, package manager, and relevant lockfile. Do not paste the whole environment or the values of environment variables.

Review the output before sharing it. Home-directory names, email addresses, tokens, cookies, customer data, and private repository paths do not belong in a public issue.

4. Give a coding agent a bounded job

A useful reproduction prompt has an explicit stop condition:

Attempt the reported command in this authorized checkout.
Do not edit production code.
Report the exact command, exit status, expected value, actual value,
and whether the failure reproduced twice from a clean state.
Stop after the evidence is captured.

This keeps reproduction separate from diagnosis and implementation. A passing test in a different harness does not disprove the original report; the command and environment must match the claimed trigger.

5. Package the evidence for the maintainer

A complete issue can stay short:

one-sentence symptom;
exact reproduction steps;
expected and actual results;
environment summary;
frequency and negative control;
link to the smallest public reproduction;
limits on what was observed.

The free OSS Bug Repro Lite repository contains a copy-ready GitHub Issue form, a portable REPRO.md, and a synthetic worked example:

https://github.com/williamgritti/oss-bug-repro-lite

I also made an expanded pack with a local environment collector and sanitizer, Node.js and Python starters, four bounded coding-agent prompts, examples, tests, and checksum verification:

https://ko-fi.com/s/2c05325e27

The expanded pack is a paid digital product. It runs locally, makes no network requests, and requires Node.js 20 or later for the collector. It organizes evidence; it does not diagnose or fix a bug.