How to Write Good Bug Reports (PM Guide)
A well-written bug report saves hours of engineering time. A poorly written one creates back-and-forth that delays the fix and frustrates the team. PMs file bugs frequently and should be able to write reports that engineers can reproduce and fix without follow-up questions.
This guide covers the format and content that makes bug reports immediately actionable.
Step-by-step guide
Step 1: Write a descriptive title
The title should describe the symptom, not the diagnosis. Good: "Search results page shows 0 results for queries with special characters." Bad: "Search is broken." The title should let someone scanning a bug list understand the issue without opening it.
Step 2: Document exact reproduction steps
Write numbered steps that an engineer can follow to reproduce the bug. Start from a known state: "1. Log in as a workspace admin. 2. Navigate to Settings > Members. 3. Click Invite Member. 4. Enter an email with a plus sign (test+1@example.com). 5. Click Send." Include the exact data and inputs used.
Step 3: Specify expected vs. actual behavior
Explicitly state what should happen and what actually happens. "Expected: Invitation is sent successfully. Actual: Error toast appears saying 'Invalid email address.'" This eliminates ambiguity about whether the behavior is a bug or expected.
Step 4: Include environment details
Note the browser and version, operating system, device type, user role, and any relevant account state. Some bugs only occur in specific environments. Include whether the bug reproduces in production, staging, or both.
Step 5: Attach evidence
Screenshots, screen recordings, console errors, and network request details make bugs much easier to diagnose. A 10-second screen recording showing the bug is more valuable than five paragraphs describing it.
Step 6: Classify severity and impact
Assign severity: P0 (service outage or data loss), P1 (major feature broken, no workaround), P2 (feature broken, workaround exists), P3 (minor issue, cosmetic). Include impact: how many users are affected and whether there is a workaround.
Common mistakes
Vague reproduction steps
"Go to the settings page and something breaks" is not reproducible. Every step must be specific enough that a new team member could follow them without prior knowledge of the system.
Diagnosing instead of describing
"The database query is slow" is a diagnosis, not a bug report. Describe the symptom: "Dashboard takes 15 seconds to load after login." Let engineers diagnose the cause. They have access to more diagnostic tools than you do.
Not checking if it already exists
Before filing a new bug, search the issue tracker for similar reports. Duplicate bugs waste triage time and make the bug backlog harder to manage.
Missing severity classification
Bugs without severity default to "when we get to it." Always assign severity so the team can prioritize correctly. A P0 bug gets fixed immediately; a P3 bug can wait for the next sprint.
Tips
- Use browser developer tools to capture console errors and network failures
- Note whether the bug is consistent (every time) or intermittent (sometimes)
- Include the user impact: "Affects all users" vs. "Only affects admin users with 50+ members"
- If you found a workaround, include it so users have a temporary solution
How Vantage helps
Vantage generates tickets with acceptance criteria that define expected behavior. When a shipped feature deviates from its acceptance criteria, the PM has a clear reference for writing the bug report: the expected behavior is already documented in the ticket.