1 / 2 · Book 21 · Bug Report Diplomacy · drill: interview Q&A⊞ allnext →Get the book →
1.3The CLEAR Framework for Bug Reports
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" |
Extended CLEAR: Additional Elements for Complex Bugs
For bugs that involve multiple systems, intermittent behavior, or subtle data issues, extend the CLEAR framework with these additional elements:
| Element | When to Include | Example |
|---|---|---|
| Frequency | Intermittent bugs | "Reproduces approximately 3 out of 10 attempts" |
| Workaround | If one exists | "Refreshing the page and retrying resolves the issue" |
| Hypothesis | When you have a theory about root cause | "May be related to the caching layer -- clears after TTL expires" |
| Related Tickets | When connected to other issues | "Possibly related to SHOP-456 (similar validation gap)" |
| Attachments | Always when possible | Screenshots, screen recordings, network logs, console output |