Bug Reporting
"How we document bugs in Linear with reproduction steps, environments, and expected behavior before writing a fix."
Why this exists
Half-documented bugs get fixed once and then return. If the root cause isn't written down, the next developer starts from zero. We write complete bug reports because incomplete ones cost days of duplicated research.
Operational Flow
File before fixing: Create the Linear ticket before debugging. If you find a new bug while fixing another, file it immediately.
Use the template: Complete the Title, Environment, Steps to Reproduce, Expected Behavior, Actual Behavior, and Severity fields.
Attach evidence: Include screenshots, screen recordings, logs, or Sentry links. Vague reports are ignored.
Tag the system: Add component labels (e.g., auth, billing, API) to help track ticket patterns.
Link related tickets: Reference past issues or postmortems before starting work.
Close with a root cause: Add a one-sentence note explaining why the system broke, not just what lines you changed.
What good looks like
- A developer with zero project context reproduces a bug in ten minutes using only the ticket details.
- A client-reported bug is logged with Sentry logs and replication steps within 30 minutes of receipt.
- A search for auth bugs shows a clear history of what broke and why, prompting a structural database fix.
What NOT to do
- Don't fix a bug without filing a ticket first. The fix is temporary, but the documentation is permanent.
- Don't write 'intermittent bug' without data. Intermittent issues require user IDs, logs, and timestamps.
- Don't set severity based on personal frustration. Rate it by client impact and frequency.
- Don't copy client descriptions directly. Test and replicate the bug yourself first.
A bug report is the first draft of institutional memory. The reproduction steps you skip to save time are the exact details your teammate will need at midnight when the bug returns. We use Linear because it links commits directly to tickets, but the tool only works if you write the ticket before writing the code.
The most common mistake is fixing a bug in five minutes and then closing a ticket named ‘fixed auth redirect’ with no explanation. That record is useless. Write the report first so someone who was not in the room can understand the issue. The extra ten minutes is not administrative overhead. It is the job.