Why bug reports fail
Most bug reports fail for one of three reasons:
- 1The developer can't reproduce the issue
- 2The severity is wrong (either under- or over-stated)
- 3The expected behavior is ambiguous
A well-structured bug report solves all three before anyone has to ask.
The 5 elements every bug report needs
1. A title that describes the *behavior*, not the component
Bad: "Login broken" Good: "Login form submits but redirects to 404 instead of dashboard when email contains uppercase letters"
The first tells a developer almost nothing. The second tells them exactly where to look.
2. Steps to reproduce — numbered, specific, complete
Include every step, even the obvious ones. "Obvious" is subjective, and you want zero ambiguity.
1. Navigate to /login
2. Enter email: Test@Example.com (note uppercase T and E)
3. Enter password: ValidPass1
4. Click "Sign in"
5. Observe: page redirects to /404 instead of /dashboardInclude environment details: browser, OS, screen size, any cookies or local storage state, whether the user is logged in as a specific role.
3. Expected vs. actual behavior
These are two separate fields for a reason. Don't conflate them.
- Expected: Successful login redirects to /dashboard
- Actual: Page redirects to /404
If you only write "login doesn't work," the developer has to interview you to understand what "work" means.
4. Correct severity
This is where most bug reports go wrong. Severity describes impact; priority describes urgency. They are different.
| Severity | Meaning |
|---|---|
| Critical | Data loss, security breach, complete feature down for all users |
| High | Major feature broken for a significant portion of users |
| Medium | Feature works but with significant UX friction; workaround exists |
| Low | Cosmetic issue, minor UX problem, edge case |
Inflating severity to get bugs fixed faster erodes trust. If everything is critical, nothing is.
5. Evidence: screenshot, video, or network log
A screenshot removes all ambiguity about the visual state. A short screen recording showing the exact steps is even better. Network logs (from DevTools) are invaluable for API bugs.
Tools like softAssert let you annotate screenshots directly so you can circle the exact element that's broken.
The AI shortcut for severity
Deciding severity is genuinely hard — it requires knowing the app's user base, the business impact, and the current risk tolerance of the team. softAssert's AI severity suggestion considers these factors based on your project context and suggests a starting point.
You still make the call. But having a justified starting point speeds up the triage conversation significantly.
A template you can use right now
**Title:** [Component/Feature] [Behavior description]
**Environment:**
- Browser: Chrome 124 / macOS Sonoma
- User role: Admin
- Account state: Logged in, payment plan: Pro
**Steps to reproduce:**
1. ...
2. ...
3. ...
**Expected:** ...
**Actual:** ...
**Severity:** High — [one-sentence justification]
**Evidence:** [screenshot / video / log attached]
**Workaround:** [if any]Copy it into your team's Jira or Linear template. Your future self (and every developer you work with) will thank you.