How to Report a Bug Developers and Agents Can Fix

How to report a bug, in one pass: name the exact control, write the shortest repro, state what you saw and what you expected, and attach a crop that shows only that control. If an AI coding agent will touch the ticket, also attach the named Accessibility element, not just a full-screen PNG.

Most templates stop at "steps, actual, expected." That is necessary and still not enough when the product has three buttons that all look like Save.

What must every bug report contain?

Four fields, every time. Skip one and you are writing a bounce.

Control. Not "the button." The label, the screen, and which of several identical rows. If you can, the AX role and name.

Repro. The shortest path from a known state. Numbered. One action per line.

Actual. What happened, including the exact string, color, or layout failure.

Expected. What the spec or last good build did.

Environment is the fifth field people remember: OS, build, account type, locale. Put it at the bottom so it does not bury the repro.

The format of a bug report page is the template cut. The bug report example page is a filled one. This page is the method.

How to report a bug without writing a novel

Testers write novels when they do not trust the screenshot. The fix is a better capture, not a longer paragraph.

Open the broken build. Get to the state. Hold ⌥⌘A, circle the control, and speak the actual versus expected while you still see it.

On-device transcription turns that sentence into text. The hit-test turns the circle into role, label, and frame. Confidence and circled-versus-dwelled provenance ride along so nobody pretends a hover was a deliberate mark.

File that bundle to Linear or GitHub. The point-and-speak Linear and GitHub flow is the tracker version.

If you must type, keep the prose under the capture, not instead of it. One sentence of actual, one of expected, then the numbered path.

A typed skeleton that still works

Title: Settings → Notifications → "Email alerts" toggle does not persist.

Control: Toggle labeled Email alerts, Notifications pane, Settings window.

Repro:

1. Launch build 2026.08.21.
2. Open Settings → Notifications.
3. Turn Email alerts off.
4. Quit and relaunch.
5. Open the same pane.

Actual: Toggle is on.

Expected: Toggle stays off.

Attach: Crop of that toggle, plus the named element if you captured it.

That is a complete report. A four-paragraph essay about "notifications feeling broken" is not.

How to report a visual bug

Visual bugs die in Slack because the crop is the whole window.

Zoom to the broken spacing. Circle only the gap. Say the measurement if you have one ("these should be 8pt, they are flush").

If the surface is a canvas or a game view, the AX tree may be empty. Say that. An OCR fallback can still grab the glyphs, and confidence should stay honest below about 0.8.

Multi-display setups need the monitor named. A mark that remembers which screen it was drawn on saves a "works on my laptop" thread.

Scrollable pages need pause. ⌥⌘P lets a capture span a long view. Scrolled marks should keep their own frame so the crop is not the wrong scroll position.

How to report a bug an AI agent can fix

Agents fail on vague nouns. "This" means nothing in a ticket without a pointer trail.

A good agent-ready report includes the resolved element path, the spoken instruction split per mark, a cropped screenshot, and enough window text to see neighbors. PinVari can attach focused-window text up to 40,000 characters, including text scrolled out of view, plus an interactive-element map.

Connect the capture tool to Claude Code, Cursor, Codex, or Zed over local MCP. One click inside PinVari → Connect, or:

claude mcp add --scope user pinvari -- "$HOME/.pinvari/mcp/pinvari-mcp"

The app must be running on 127.0.0.1:3402. pinvari_next_instruction is the pull. pinvari_mark_done closes the item. Mid-fix, pinvari_request_capture can ask you to point again.

Do not paste a 4x retina full-screen shot into the agent as your only context. That is a token bill and a wrong-component edit. The bug reporting software comparison is the tool landscape; this page stays on the report itself.

What should you leave out of a bug report?

Speculation about the root cause, unless you can prove it. "Probably a race" trains the reader to argue.

Logs you did not read. Attach them, do not paste a megabyte into the description.

Five screenshots of the same window. One crop, one context shot if the crop is tiny.

Customer names and secrets. A capture tool that stays on-device by default is easier to keep clean than a cloud recorder. PinVari transcribes and OCRs on the Mac and uploads nothing unless you file or hand off.

Severity theater. "Blocker" on a typo trains people to ignore you. Use the team's real scale.

A QA pass you can run in five minutes

1. Reset to a known account and build number.
2. Walk the shortest path once without writing.
3. Walk it again while capturing. Circle, speak, finish with return or ⌥⌘A.
4. Check the Command Center: right app, right mark, right words.
5. File to Linear or GitHub, or leave it on the MCP queue for the developer who lives in Claude Code.
6. If the developer pings "which button," your report failed. Fix the control line, do not argue.

Crash-safe session recovery matters when the build under test dies mid-capture. So does grouping captures by app, so a Settings pass does not mix with a Finder pass.

Hotkeys to keep in the muscle: ⌥⌘A mark, ⌥⌘V voice-only, ⌥⌘P pause/resume. macOS 14+, Apple Silicon and Intel, notarized Developer-ID DMG.

If the team wants a one-time Mac seat instead of another SaaS, launch pricing is $39 for the first 500 licenses, then $59, via Polar, team seats available, no subscription on the core app. The pricing block is current.

How to report a bug across iOS webviews and Mac desktop

QA often owns both a webview and a native pane in the same sprint. The report format does not change. The capture surface does.

For the webview, include the real URL from the browser AXWebArea. For the native pane, include the window title and the AX label.

Do not merge those two into "Settings is broken." File one report per surface so the assignee is not bouncing the ticket between teams.

If the same sentence applies to both, duplicate the capture. Two named elements beat one paragraph that pretends they are the same control.

Agents assigned to only the Mac repo will otherwise "fix" a web copy issue in the wrong tree. Humans do the same thing when the screenshot is a phone frame pasted into a desktop ticket.

FAQ

What is the correct way to report a bug?

Name the control, give the shortest numbered repro, state actual and expected, and attach a crop of that control. Add environment last. If an agent will fix it, include the named UI element as well as the picture.

How do I report a bug in Jira or Linear?

Same fields. The tracker is a mailbox. A Linear issue with a vague title and a full-screen PNG is still a bad report. Put the control in the title and the repro in the first comment.

How do you report a visual UI bug?

Circle only the broken spacing or color, say the expected value, and include build plus display. Full-window shots hide the defect. Name the element when the OS can see it.

What makes a bug report reproducible?

A known starting state, one action per step, and no hidden setup. If the bug needs a specific flag or locale, write that as step zero. If you cannot reproduce it twice, say so.

Should QA write bug reports for AI coding agents?

Yes, if the team ships that way. Agents need names, not vibe. A capture that resolves the Accessibility node plus a short spoken actual/expected beats a paragraph of "looks wrong."

How long should a bug report be?

Short enough to read on a phone. Two sentences of symptom, a short list of steps, one crop. Length is not rigor. Named controls are rigor.