Write the report
someone else can fix.

Name the failure

The title is the whole report for anyone scanning a list. Write what broke.

• “Checkout total ignores the promo code” can be fixed. “Bug,” “It’s broken,” and “Checkout issue” cannot.
• Name the page when the list only shows the title.
• One failure per report. Two bugs in one ticket get one fix and a leftover.

Number what you did

A promo code, a total, and a button are enough. A paragraph about the afternoon is not.

1. Open the cart with the canvas tote.
2. Apply SUMMER.
3. The line shows −$20.00. The total stays $84.00.

• Use a numbered list. Someone else should be able to follow it without you in the room.
• Include the value that matters. SUMMER, $84.00, and Pay are the bug. “The discount” is not.
• If it only happens sometimes, say so. “Once, after a refresh” beats “always” when you are not sure.

Say what should have happened

A description of the bug can be read as the intended behavior. Write both sides.

• Expected: the total is $64.00, and Pay charges that.
• What happened: Pay charges $84.00. The card is declined because the charge does not match the discounted order.
• Be precise. “The wrong total” leaves the reader to guess which number was wrong.

Mark the part that is wrong

A sentence does not show which total. Capture the viewport you were looking at.

• Circle the wrong number, or box the button.
• Keep the unmarked screenshot beside the drawing. The marks should not cover the evidence.
• Make the failure more obvious in the drawing than it was in the title.

Point at the element

The node, its HTML, and the CSS that matched are how someone finds it in the code.

• Point when you can tell which element it is.
• Skip the picker when you cannot. A report without a picked element is still a report.
• The selector is a path to the node. It is not a replacement for the steps.

Keep the moment before the click

About the last 30 seconds is enough. A recording of the whole visit hides the failure.

• The URL and the browser belong on the ticket.
• If a price came back wrong, the network call is the bug. If the page threw, the console is the bug.
• Do not paste a stack trace into the description when it is already attached.

Leave the secrets out

The report needs the failure. It does not need the password, the card, or anything typed into a field that is not the bug.

• Masked inputs are the right default.
• A repro step can say “sign in as a test customer” without the password.
• If a secret is already in a screenshot, say so. Do not also type it into the description.