Initializing/60 FPS
·4 min read

Bug Reporting Etiquette

A practical guide for everyone — how to report internal bugs with low friction and high signal, and how responders should handle them.

Kai Schönberger
Kai SchönbergerSoftware Engineer
Engineering CultureQualityCommunicationTeamwork

Reporting bugs internally is important to catch issues before the users do and to improve quality in general. The goal should be to keep the friction low so that people do not hesitate to report their findings, while at the same time keeping a minimum quality bar so that developers do not waste their time or get frustrated with reports they cannot really act on.

For Reporters (Everyone)#

  • Use the right channel: It all starts with finding the right place to report an issue. In our case this is mostly Slack. Use domain- or feature-specific channels if available. Avoid sending DMs to someone who you think has worked on this exact thing unless you are sure about it. It’s much easier to tag others — or even bring in AI agents — when conversations and context are kept in public.
  • State facts, not guesses: Describe what you saw happen, and avoid drawing premature conclusions and only sharing those as the bug report. Guessing the root cause can mislead the developer investigating into a totally wrong direction.
  • Keep reports separate: Report only one bug per ticket or thread so it is easy to track and respond. For example, use one Slack thread per issue rather than bundling multiple unrelated findings into a single thread.
  • Mind your language: Don’t call every bug or issue “weird” or “strange”. At the end of the day it’s someone else’s work, so try to observe and describe the behavior without immediate judgement.
  • Stay engaged: Respond quickly if the investigator asks follow-up questions. Don’t leave them waiting for days or go silent after ringing the bell initially.
  • Never just say “XYZ does not work”: I’ve heard this countless times and it’s never really helpful to simply say something does not work — especially when it isn’t immediately reproducible for everyone. State what you actually observed that makes you feel it doesn’t work, e.g., “No reaction at all after pressing button XYZ” or “Loading screen stays infinitely”.
  • Add rich context: You might be busy and want to resume your own work, but especially in the era of AI agents helping to troubleshoot, it’s important to include as much detail as possible upfront. Once a developer or agent picks up the report, missing context turns a five-minute fix into a multi-day ping-pong.
  • List reproduction steps: Write down numbered, step-by-step instructions on how to make the bug happen again.
  • Compare behavior: Clearly state what you expected to happen versus what actually happened.
  • Add visual proof: Attach screenshots or a short screen recording to show the exact issue in action.
  • Include logs: Copy and paste the full error text and console logs instead of just paraphrasing or describing them.
  • Share your environment: Not always relevant, but especially for UI glitches, layout issues, or browser-specific bugs, include your operating system, device type, software version, and browser.

For Responders#

Good bug reporting etiquette goes both ways. When someone takes the time to write a thoughtful report, how you respond shapes whether they will keep reporting issues in the future:

  • Don’t leave them hanging: Acknowledge the report promptly — even a quick reaction or short reply lets the reporter know their finding was seen and someone is looking into it.
  • Give estimates, but be conservative: Let the reporter know roughly when they can expect a fix or an update, and pad your estimate so you under-promise and over-deliver.
  • Create a ticket as a reference: If the issue cannot be fixed immediately, turn it into a tracked ticket so it doesn’t get lost in chat history.
  • Cross-link conversation and ticket: Link the Slack conversation inside the ticket and post the ticket link back into the conversation thread so anyone following along has full context in both places.