# Turn a Vague Bug Report into Evidence a Maintainer Can Rerun > Source: > Published: 2026-09-11 09:36:46+00:00 “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. 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: ``` php 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](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](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.