The five questions that turn a vague issue into work someone can start

The expensive thing about a vague issue is not the vagueness. It is the round trip.

Somebody files "export is broken" on a Thursday afternoon. A developer picks it up on Monday, reads it twice, and asks which export. The reporter is in a different timezone, sees the question on Tuesday, and answers on Wednesday. Four working days have gone by and nobody has written a line of code or learned anything they could not have learned on Thursday.

The fix is not better reporters. It is asking the questions at the moment the issue is filed, while the person still has the failure in front of them and the context in their head. There are five that do almost all of the work.

1. What did you expect to happen?

This sounds like the softest question of the five and it is usually the most valuable, because it is the only one that recovers the reporter's mental model. "Export is broken" tells you a fact about the software. "I expected the CSV to contain every row I could see on screen" tells you what the software is for, in this person's hands, which is the thing you need in order to decide whether it is broken at all.

A surprising share of bug reports turn out to be disagreements about intended behaviour. Those are worth finding on day one, because they are product decisions wearing a bug's clothing, and they do not belong in an engineer's queue at all.

2. What happened instead?

Specifically, and preferably literally. "It failed" can mean an error dialog, a silent no-op, a spinner that never resolves, a partial result, or a result that looks fine and is wrong. Those are five different defects with five different owners.

The word to be suspicious of is "sometimes". Sometimes usually means "I have not worked out the pattern yet", and the pattern is often the entire bug. It is worth asking directly: does it fail on every attempt, or did it fail once and you moved on?

3. How do I get there from a clean start?

Reproduction steps are the one thing everybody already knows to ask for, and the one thing most often supplied in a form that does not work: steps that begin halfway through, from a state the reporter had already built up.

The useful version starts from something the reader can also reach. A fresh session, a named test account, a specific record. If a step reads "open the report you made earlier", the ticket is not reproducible by anyone except its author.

4. How many people, how often, and since when?

Three questions in one, and together they set the priority, which is not the reporter's job to guess but is very much their information to give.

"Since when" is the highest-yield half of it. If something worked last week and does not work now, the search space collapses to what changed in between, and the ticket has effectively told you where to look. If it has never worked, you are dealing with a missing feature and a disappointed expectation, which is a different conversation.

5. What have you already ruled out?

Almost nobody volunteers this and almost everybody has some. People try things before they file. They refresh, they try a different browser, they ask a colleague whether it happens to them too. That work disappears if nobody asks for it, and the developer repeats it.

It also changes the tone of the ticket, from a demand to a handover. The reporter has done something, and the ticket says so.

What that looks like in practice

The second version is not longer because the reporter tried harder. It is longer because somebody asked. The 1,000 in that description is the whole bug, and it was in the reporter's head from the start.

Why teams do not ask

Everybody agrees these are the right questions. Very few teams ask them consistently, and the reason is social rather than technical.

Asking a colleague to fill in a form feels like a rebuke, especially when the colleague is senior, or in another department, or a customer. So the developer guesses, or context-switches to go and ask in person, or quietly lets the ticket rot in triage. The questions do not get asked because there is no neutral party to ask them.

Issue templates are the usual answer and they help, but they ask everybody the same thing regardless of what the issue actually says, so they are mostly ignored or filled in with "N/A". The questions that matter are the ones that follow from this report: nobody needs to be asked for reproduction steps on a feature request.

The checklist

• Expected: what should have happened, in the reporter's own words.
• Actual: what happened instead, literally, including "nothing".
• Path: steps from a state the reader can also reach.
• Scope: how many people, how often, and since when.
• Ruled out: what has already been tried.

Five answers, usually five minutes, almost always on the day it is filed rather than the following Wednesday. That is the whole saving, and it is larger than it looks.