“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 up source code or diagnostic data to a third-party service.
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.
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.
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.
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.
A complete issue can stay short:
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.
Built with AI assistance. Each shipped file was individually reviewed. Executable behavior and the packaged artifact were verified with automated tests and clean-extraction checks.