1.3Writing Bug Reports That Developers Want to Fix
A great bug report answers every question the developer will have before they ask it. The goal is to minimize the back-and-forth and make fixing the bug the path of least resistance.
The CLEAR Framework
| Element | What It Means | Example |
|---|---|---|
| Context | Where does this happen? Environment, user role, preconditions | "Staging, logged in as admin, with 2FA enabled" |
| Location | Exact URL, screen, API endpoint, or code path | "POST /api/v2/orders, response body" |
| Expected | What should happen according to the spec or common sense | "Order total should include the 10% discount" |
| Actual | What actually happens, with evidence | "Order total is $110.00 instead of $99.00" |
| Reproduction | Step-by-step instructions anyone can follow | "1. Add item X to cart 2. Apply code SAVE10 3. Click checkout" |
Example: Bad Bug Report
Title: Discount not working
Description: The discount code doesn't work. Please fix.
This report forces the developer to ask: Which discount code? Which product? Which environment? What did you expect? What did you see? Every question is a round trip that wastes both people's time.
Example: Good Bug Report
Title: 10% discount code SAVE10 not applied to order total on checkout page
Environment: Staging (v2.4.1), Chrome 121, logged in as test-user-03
Steps to reproduce:
- Add "Wireless Headphones" (SKU: WH-200) to cart
- Navigate to cart page
- Enter discount code "SAVE10" and click "Apply"
- Success message "Discount applied" appears
- Click "Proceed to Checkout"
Expected: Order total should be $99.00 ($110.00 - 10% discount)
Actual: Order total shows $110.00. The discount success message appeared but the total was not recalculated.
Additional context: The discount works correctly on the cart page (shows $99.00) but reverts on the checkout page. This may be a state management issue between the cart and checkout components.
Attachments: Screenshot of cart page (discount applied), screenshot of checkout page (discount missing)
What Makes the Good Report Effective
- The developer can reproduce the issue in under 2 minutes
- The title is specific enough to find later
- The "additional context" offers a hypothesis without being prescriptive
- Evidence is attached, not described from memory
- No blame, no frustration, just facts