5.2The Five Essential Fields

Every bug report, regardless of your tracking tool (Jira, Linear, GitHub Issues, Bugzilla), must include these five fields:

1. Environment

OS, browser/version, device, API version, build number, feature flags enabled. This is the "where" of the bug.

Environment: Chrome 122, macOS 14.3, staging environment, build #4521
Feature flags: new_checkout_flow=true, dark_mode=false

Without environment details, the developer's first question is "what browser?" — and the bug report is already delayed.

2. Steps to Reproduce

Numbered, minimal. Strip away anything that is not required to trigger the bug. If you can reproduce with 3 steps, do not include 10.

Steps to Reproduce:
1. Navigate to https://staging.example.com/login
2. Enter email: user+tag@test.com
3. Enter password: ValidPass123!
4. Click "Sign In"

Minimal means minimal. Do not include "Open browser" as a step. Do not include navigation through the homepage if a direct URL works. The goal is the shortest path to the bug.

3. Expected Result

What the spec, design, or common sense says should happen. Be specific about the observable behavior.

Expected: User is authenticated and redirected to /dashboard.
The welcome message "Hello, user+tag@test.com" is displayed.

4. Actual Result

What actually happened. Include evidence: screenshots, console errors, network traces, response bodies.

Actual: Server returns HTTP 500. Response body: {"error": "invalid_parameter"}.
No client-side errors in the console. Network tab shows the POST /auth/login
request failed with 500.

5. Severity and Priority

See the Severity vs Priority file for details. Always include both.