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