Actionable bug reports

Bug Reporting

One problem per report, written for the person who will fix it: facts, not opinions, and evidence for every claim.

The report, always in this order

1. Problem: one line, "[Component]: [observable symptom] when [condition]" (Cart: items duplicated on rapid "Add to cart"). Use the application's own terms; never "it doesn't work".
2. Severity, by user and business impact, with the same four values a review's findings use:
   • critical: unusable, data lost or corrupted, money moved wrongly, security or tenant isolation broken. Blocks the merge.
   • major: a main flow broken without a workaround, an acceptance criterion failed, or many users affected. Fix before merging.
   • minor: impaired but with a workaround, or a small feature or rare case broken. Never blocks.
   • suggestion: cosmetic, or an optional improvement. If the urgency differs from the severity (a demo tomorrow, a feature not yet launched), say so separately.
3. Evidence: the exact error and where it appeared, log lines with timestamps and request ids, the failing request and response, console output or a screenshot, the failing test's output. Redact secrets and personal data.
4. Reproduction: environment and version; preconditions (role, data, state); numbered steps with exact inputs; expected result; actual result; how often (always, 3 of 10). Mark the trigger and say what does not trigger it.
5. Consequence: who is affected, how many, what it costs them or the business, and any workaround.
6. Suggested fix: the root cause with the function or module, or the most likely area and the hypothesis behind it. Say which of the two it is.
7. Verification: how the fix will be proven: the original reproduction, a regression test that fails before and passes after, and the neighboring flows to recheck.

Before reporting

• Reproduce it yourself and cut the steps to the minimum. Look for an existing report and add to it instead of filing a duplicate.
• Spend a few minutes narrowing the conditions; it saves the fixer far more.
• Keep the symptom and the cause apart, and never present a guess as the cause.

Verifying before closing

No status claim without fresh evidence from this run:

1. Name the check that proves the claim, run it in full, and read the whole output and the exit code.
2. Re-run the original reproduction: the symptom is gone.
3. Prove the regression test: it fails without the fix and passes with it.
4. Recheck the directly affected flows and run the relevant test suite.
5. Report what ran and passed, what failed, and what did not run and why.

• "Should", "probably" or "seems to" in a status means the check has not been done.
• Never close or mark fixed on a partial check; report the remaining gap instead.

Anti-patterns

Vague titles; several bugs in one report; opinions as facts ("ugly" is not a bug, "truncated text" is); no environment; no evidence; blame; filing before investigating; closing without a regression test.