# How to write a bug report that gets fixed

> Give the person fixing your bug everything they need to reproduce it: what to capture, how to annotate the steps, and what to redact, so your report doesn't end in 'unable to reproduce.'

The difference between a bug report that gets fixed and one that sits in a queue is almost never the bug. It's the evidence. Most of the time, "unable to reproduce" means *your screenshot didn't show the thing I needed to see.*

The person fixing it wasn't at your desk when it happened. Your capture is the only look they get. Here's how to make sure it shows them everything they need.

## Capture the whole window, not just the error

The error message tells them something went wrong. The rest of the screen tells them where, and often why. Prefer a **window capture** (`⌘⇧W` on macOS or `Ctrl+Shift+W` on Windows) of the whole app — title bar, toolbar, whatever state is visible — over a tight crop of just the red text. The person fixing this needs to know which screen you were on, what was open, what was selected. If the reproduction depends on a menu or a hover state, that's what you're capturing: use the **delayed capture** (`⌘⇧7` on macOS or `Ctrl+Shift+7` on Windows) so the dropdown is still open when the frame fires.

If the problem *moves* — a flicker, a race, an animation that stutters — that's a multi-frame job. Take the region capture, open the timeline, and you've got the burst: nudge through the frames and pick the one where it visibly goes wrong. A single static frame of a flickering control proves nothing. Three frames do.

## Annotate the steps, not the opinion

Number the steps. The **counter (C)** exists for exactly this: click at each step of the repro and the tool hands you ①②③, so the reader follows your exact path in order. Add an **arrow (A)** for anything that's easy to miss, and a **spotlight (S)** if the screen is busy and the important part is small.

Two rules keep it honest:

- Point at what you *did*, not at what you *feel*. "Clicked here, then here, then it did this" reproduces. "This is broken" doesn't.
- One frame per idea. If the report needs four distinct facts, it needs four annotated frames — or one `.hypercapture` with a timeline the reader can scrub.

*Number the steps and point at what broke, so they can follow along.*

## Redact before you send it

Your report is leaving your machine and probably your company. Before you send it, sweep it with the **redact tool (X)**: account names, customer data, keys, the URL in the address bar if it's internal. When it's truly sensitive, use **Secure** (a solid block) rather than blur: a block covers the text completely, while a blur can leave enough behind to make it out.

## Send it so nothing gets lost

Two options, in order of usefulness:

- **The fast one:** copy the annotated image (**⌘C / Ctrl+C**) and paste it straight into the ticket. Fine for one frame.
- **The complete one:** save the `.hypercapture` and attach it. The recipient opens it in hypershot and everything is still there to work with — every arrow movable, the timeline scrubbable, the original frames intact.

## The report that gets fixed

The whole window captured. Steps numbered. The one thing that mattered spotlighted. Everything private redacted. Sent as a file they can open and explore.

It can still come back "unable to reproduce." It's just a lot less likely now.

---

From https://hypernuclear.com/blog/bug-report-that-gets-fixed/