01 Overview
A bug report is not a complaint; it is an argument. Like any argument, it stands or falls on the quality of its evidence. Adjectives such as broken, slow, or weird are conclusions, not observations. They tell the reader what you felt, not what you saw. The craft of a strong report is the craft of replacing every adjective with a fact that another person can verify. That means describing the exact conditions, the exact actions, and the exact result, in language that leaves no room for interpretation.
This article is about that craft. It is written for testers and engineers who want their reports to survive triage, to be reproducible by someone who has never seen the feature, and to be fixed without a round of clarifying questions. The goal is not to make reports longer; it is to make them denser with evidence. A short report full of precise observations will always outperform a long report full of opinion. The difference between a report that gets fixed and one that gets bounced is usually not the severity of the defect but the clarity of the evidence.
We will look at what a report is actually claiming, how severity and priority differ, how to write steps that someone else can follow, how triage uses your evidence, what to do when a defect comes back, and common questions. Throughout, the theme is the same: evidence beats adjectives.
02 What the report is actually claiming
Every bug report makes a claim: under these conditions, this action produces this result, and that result is wrong. The claim has three parts: the setup, the action, and the observed outcome. If any part is missing or vague, the claim is incomplete. For example, saying the save button is broken is not a claim; it is a verdict. A claim would be: with a new document open, entering text and clicking Save produces a spinner that never resolves, and the document is not written to disk. That is something another person can test.
The evidence in a report is whatever supports the claim. Screenshots, logs, error messages, and exact input values are evidence. So is a clear statement of what you expected to happen and why. Expectations are not opinions when they come from a specification, a design document, or a reasonable user assumption. The strongest reports separate observation from interpretation: here is what I did, here is what I saw, here is what I expected, and here is why I believe the difference matters.
When you write a report, ask yourself what a skeptical reader would need to believe you. They cannot see your screen. They do not know your data. They may not know the feature as well as you do. Your job is to give them everything they need to reproduce the claim without asking you a single question. That is the standard. Adjectives like major or annoying do not meet it; precise observations do.
03 Severity versus priority
Severity and priority are often confused because both are expressed as levels, but they answer different questions. Severity describes how much damage the defect causes: does it crash the application, corrupt data, block a core workflow, or merely misalign a label? Priority describes when the team intends to fix it: now, next, later, or never. A defect can be high severity and low priority, or low severity and high priority. A crash in a rarely used admin tool might be high severity but low priority. A typo on the homepage might be low severity but high priority because it is the first thing every visitor sees.
The mistake testers make is inflating severity to get attention. That works once, then it erodes trust. If everything is critical, nothing is. The better approach is to state severity as objectively as you can, using the impact on users, data, or system stability. Then state priority as a recommendation, not a demand. You can say this blocks the checkout flow for all users, which is a severity statement, and it should be fixed before the next release, which is a priority recommendation. The triage team will make the final call, but your evidence gives them a solid basis.
Remember that severity is a property of the defect, while priority is a property of the business context. The same defect can have different priorities at different times. A workaround might lower priority without changing severity. A upcoming release might raise priority without changing severity. Keeping the two separate in your report helps everyone reason clearly about what to do next.
04 Writing steps someone else can follow
The reproduction steps are the heart of the report. They are the shortest reliable path to the defect. Shortest matters because extra steps add noise and make it harder to isolate the cause. Reliable matters because a defect that only reproduces sometimes is much harder to fix. Write steps as a numbered sequence of actions, each one concrete enough that a reader can perform it without guessing. Start from a known state: a fresh install, a new account, a cleared cache, or a specific data setup. If the defect depends on particular data, include that data or explain how to create it.
Avoid combining multiple actions into one step. Click the menu and select export is two actions; if the defect occurs between them, the reader cannot tell where. Avoid vague verbs like test or verify; they do not tell the reader what to do. Instead, say open the file menu and choose Export as PDF. After each action, state what you observed. If the defect appears only after a delay, say how long. If it appears only on a particular browser or device, say which one. The goal is to make the reader feel like they are watching over your shoulder.
Finally, include the expected result and the actual result as separate statements. The expected result is what should have happened according to the design or common sense. The actual result is what you saw. This pair turns your steps into a testable claim. If you cannot write a clear expected result, you may not yet understand the defect well enough to report it. In that case, investigate a little more before filing.
05 Running the triage queue
Triage is the routing decision made at review. It is not a trial; it is a sorting process. The team reads the report, confirms the claim, assigns severity and priority, and decides who should fix it and when. Your job as the reporter is to make that decision easy. A report with clear evidence can be triaged in seconds. A report full of adjectives will be sent back for more information, which delays the fix and wastes everyone's time. The triage queue is not a place for debate; it is a place for decisions based on the evidence in front of it.
During triage, the team will ask a few standard questions. Is the defect reproducible? What is the impact? Is there a workaround? Which component is affected? What is the current status? If your report already answers these, the triage moves quickly. If it does not, the report may be marked as needing information and returned to you. That is not a rejection; it is a request for better evidence. The faster you supply it, the faster the defect moves forward. The best reporters anticipate these questions and answer them in the original report.
Triage also sets the status of the defect. Status is where the report sits in the workflow: new, triaged, in progress, fixed, verified, closed, or reopened. Each transition should be driven by evidence. A defect is not fixed until someone verifies it against the original reproduction steps. A defect is not closed until the verification passes. Your evidence is what makes those transitions meaningful. Without it, status becomes a matter of opinion, and opinions are exactly what we are trying to replace.
06 When a defect comes back
A defect that comes back after being marked fixed is a special kind of frustration. It can mean the fix was incomplete, the reproduction steps were not followed, or the defect was never fully understood. When you reopen a defect, do not simply say it is still broken. That is an adjective. Instead, provide new evidence: the steps you followed, the result you saw, and how it differs from the expected result. If the original steps no longer reproduce the defect but a variation does, document the variation. This helps the fixer understand what was missed.
Sometimes a defect comes back because the environment changed. A new browser version, a different data set, or a configuration change can expose a latent issue. In that case, your report should note what is different from the original. If you can, compare the old and new behavior side by side. If the defect is intermittent, record how often it occurs and under what conditions. Intermittent defects are the hardest to fix, so any pattern you can find is valuable. Even a negative result, such as it did not occur in ten attempts on a clean profile, is useful evidence.
When you reopen, keep the tone neutral. The goal is not to assign blame but to get the defect fixed. Assume the fixer did their best with the information they had. Your new evidence is a gift, not a rebuke. If the defect keeps coming back, it may be a sign that the root cause is deeper than the original report suggested. In that case, consider whether the report should be split into multiple defects or reframed with a clearer claim. The craft continues even after the first fix.
07 Frequently asked questions
How much detail is too much? The standard is reproducibility. If a reader can reproduce the defect without asking you a question, you have enough detail. If they cannot, you need more. Length is not the goal; completeness is. A short report with a clear video or a precise log excerpt can be better than a long report with vague prose. Always prefer the smallest amount of evidence that fully supports the claim.
What if I cannot reproduce the defect reliably? Report it anyway, but be honest about the uncertainty. State how many times you tried and how many times it occurred. Include any conditions you noticed, such as time of day, network speed, or data size. An intermittent defect with good notes is still valuable. Do not inflate severity to compensate for uncertainty; that only erodes trust. Instead, ask for help in reproducing it, and offer to gather more data.
Should I suggest a fix? You can, but keep it separate from the evidence. A suggested fix is an opinion, and it may be wrong. The evidence is what matters. If you have a strong hypothesis, label it as such and explain your reasoning. But do not let the hypothesis overshadow the observation. The best reports make the defect obvious and let the fixers decide how to address it. Remember, your job is to describe the problem precisely, not to solve it.