How to write developer-ready bug reports

A developer-ready bug report is one an engineer can reproduce without asking follow-up questions. That means stating expected vs actual behaviour, the steps to reproduce, console logs, network requests, the environment, and ideally a video or session replay, all in one place.

Seven steps to a reproducible bug report

  1. State what you expected and what happened

    Write the expected behaviour and the actual behaviour in one line each. "Clicking Save should persist the form; instead it shows a spinner forever." This single contrast tells a developer what to look for.

  2. List the steps to reproduce

    Number the exact steps from a known starting point. Reproducibility is the difference between a fix and a "cannot reproduce." Include the URL and any required state, such as a logged-in account or a specific record.

  3. Attach the console logs

    Include the browser console output. An uncaught exception or a stack trace usually points straight at the broken code, turning guesswork into a specific error.

  4. Attach the network requests

    Include the relevant network requests with status codes and timing. A 500 from an API or a request that times out explains why the UI broke, where a screenshot cannot.

  5. Record the environment

    Note the browser, version, operating system, and viewport. Many bugs are environment-specific, and this is the first thing a developer checks.

  6. Add a video or session replay

    A short recording or session replay of the actions leading up to the bug removes ambiguity. Developers can watch what happened instead of reconstructing it from prose.

  7. Share one link and send it to your tracker

    Bundle everything behind a single link and attach it to an issue in GitHub, Linear, or Jira, so the context lives with the work rather than scattered across chat threads.

Automate the checklist with Brie

Doing all of this by hand is why good bug reports are rare. Brie is a bug reporting browser extension that captures the screenshot or video, console logs, network requests, user actions, and session replay in one click, and shares them as a single link you can send to GitHub, Linear, or Jira. Sensitive data is redacted in the browser before anything is stored.

Start free

Frequently asked questions

What makes a bug report developer-ready?
A developer-ready bug report includes the expected vs actual behaviour, numbered steps to reproduce, console logs, network requests with status codes, the environment (browser and OS), and ideally a video or session replay, enough for an engineer to reproduce the issue without asking follow-up questions.
Why include console and network logs in a bug report?
Most bugs leave a trail: an error in the console or a failed request in the network tab. Including them turns "it’s broken" into a specific, reproducible problem and removes rounds of back-and-forth.
How can I capture all of this without extra work?
A bug reporting browser extension like Brie captures the screenshot or video, console logs, network requests, user actions, and session replay automatically, so a developer-ready report is one click instead of a manual checklist.