Turn "It's Broken" Into a Reproducible Bug Report

Most bug reports from non-engineers stop at "it's broken" or "I got an error." That's rarely a communication failure on the reporter's part — it's usually a form design failure. A single free-text box doesn't tell someone without technical background what information would actually help a developer fix the issue. Change how you ask, and you can pull out that information from the start.

Why "It's Broken" Is All You Get

Non-engineer reporters typically don't know the four things a developer needs: reproduction steps, expected result, actual result, and environment details. They can't write what they don't know they're supposed to provide, and a note saying "please describe in detail" doesn't fix that. What works is breaking the single question into smaller ones that surface the right information by default.

Three Common Ways Information Gets Lost

1. Steps get compressed into just the outcome

Instead of "I clicked Save and then...", reports say only "I can't save." What was clicked, what was entered, and in what order disappears, so the developer starts reproducing from scratch.

2. Expected behavior is never stated

"I got an error" alone doesn't tell you whether it's a bug or expected behavior. Without "here's what should have happened," the developer has to go back and re-read the spec before even starting to investigate.

3. Environment details are missing

Browser, screen size, login state, the kind of data being handled — without these, the issue often just won't reproduce on the developer's machine. "Works on my end" is where a lot of investigations quietly stall.

Designing the Questions — Before and After

You don't need to remove free text entirely. Put structured questions in front of it so the four essentials get captured by default.

Before: A single free-text field

• "Please describe the issue" (one text area, nothing else)

After: The question broken into parts

• "Which screen were you on, and what were you trying to do?" (anchors the starting point)
• "What did you click, in order?" (e.g. "① Save button → ② OK on the confirmation dialog")
• "What did you expect to happen?" (makes the expected result explicit)
• "What actually happened?" (separates outcome from expectation)
• "Does this happen every time, or only sometimes?" (frequency as a multiple choice)

The key is fixing the subject and the timeline of each question. Splitting the vague "what happened?" into "which screen," "after doing what," and "what did you expect" removes the guesswork for the person answering.

A Template You Can Use Today

Drop this straight into a report form or a Slack bug-report template.

1. Which screen or feature was involved?
2. What did you do right before it happened? (clicks/inputs, in order)
3. What was supposed to happen?
4. What actually happened? (full error message if there is one)
5. Does it happen every time, or only under certain actions/conditions?

Fields that can be multiple choice — frequency, browser, device type — should be dropdowns or radio buttons rather than free text. It lowers the effort for the reporter and keeps the granularity of answers consistent.

How This Plays Out in Bugoon

Bugoon's widget doesn't rely solely on free-text description. Reporters can attach a screenshot with annotations directly from the embedded widget, and click/navigation steps are captured automatically as they happen — so the actual sequence of actions is logged without anyone having to write "I clicked Save, then..." by hand.

Everything collected turns into a GitHub Issue that can be tracked on a kanban board. Pass it through the MCP server to Claude Code or Cursor, and a developer can start fixing the issue without first transcribing reproduction steps by hand.

Being able to customize the widget's question fields per project, matching the domain the team works in, could make it easier to bake the kind of question design covered in this article directly into the report form.