A Bug Report Template for Non-Technical Founders

TL;DR: A bug report works when someone who was not there can repeat your steps and see what you saw. Give them the page, the account and role, the starting state, numbered steps, what you expected, and what happened, with one problem per report. Keep your guess about the cause on its own line, and cover personal data in any screenshot before you send it.

You send “checkout is broken, please fix” to a contractor, or paste it into the chat of the tool that built your app. What comes back is a question (which page? which account?) or a fix for something that was never the problem. Neither is their fault. The sentence you sent has almost nothing they can act on.

You do not need to understand code to write a good report. You need to say what you did, in order, and what you saw. That is a skill of noticing, and a template does most of the work for you.

What does a bug report need before someone can fix it?

Start from the reader’s chair. They cannot see your screen, your account or the moment it broke. They have to recreate it, and a bug they cannot recreate is one they can only guess at. Mozilla’s bug writing guidelines put precise steps to reproduce at the top of the list. They also ask for three habits that matter just as much for a small team: say whether it happens every time, keep what you saw apart from what you suspect, and file one problem per report.

That turns into seven pieces of information:

  • Where. The full address of the page, and whether it was your published site or a builder preview. The two can behave differently, as the Bolt testing post explains, so a bug on the preview and a bug on the live site may be two different bugs.
  • Who. The account you used and its role: owner, member, guest. Say if the account is brand new.
  • Starting state. What had to be true before step one. Signed in? On which plan? Is there existing data? This is the most skipped field, and it is often the whole answer; plenty of bugs only appear for a new account, or only on a free plan.
  • Steps. Numbered, one action each, using the exact words on the buttons.
  • Expected and actual. What you thought would happen, and what did, including any error text, copied exactly.
  • How often. Every time, three out of five, once.
  • Impact. Who is stuck, in one sentence. This is how the person fixing it decides what to do first. If the report comes out of a failed check after a release, the smoke testing guide covers deciding who investigates.

What does the template look like?

Copy this into a note, a form or a ticket. Anything in square brackets is yours to fill in.

Title: [Page or feature] + [what went wrong], in about ten words

Where: [Full address of the page. Published site or preview?]
Who: [Account email used, role, new or old account]
When: [Date and time, with your time zone. Still happening?]
Device and browser: [For example, Chrome on a Windows laptop]

Starting state: [What had to be true before step 1]

Steps:
1. [One action, using the exact label on screen]
2. [One action]
3. [One action]

Expected: [What you thought would happen]
Actual: [What happened, with exact error text if there is any]

How often: [Every time / 3 out of 5 / once]
Evidence: [Screenshot or short recording, personal data covered]
Impact: [Who is blocked, in one sentence]

My guess (optional, not checked): [What you think the cause is]

Two fields do most of the work. Starting state saves the back-and-forth of “are you signed in, and on which plan?” The expected line stops the person fixing it from deciding your bug is a feature. If you do not know a field, write “not sure”. An honest “not sure” helps more than a confident wrong answer.

What does a weak report look like next to a strong one?

Here is the same bug twice. The app and the details are made up for this post.

The weak version: “Settings is broken. Changes don’t save. Please fix asap.”

The strong version:

Title: Settings page says "Saved" but the display name reverts after refresh

Where: https://app.example.com/settings (published site, not the preview)
Who: test-owner@example.com, role Owner, account created today
Device and browser: Chrome on a Windows laptop

Starting state: Signed in, on Settings > Profile, display name is "Test Owner"

Steps:
1. Change Display name to "Test Owner 2"
2. Click "Save changes"
3. Wait for the green "Saved" message
4. Refresh the page

Expected: Display name is still "Test Owner 2"
Actual: Display name is "Test Owner" again. The "Saved" message did appear in step 3.

How often: 3 out of 3 tries, also on a second browser
Evidence: Two screenshots, after Save and after refresh (test email, nothing to cover)
Impact: Anyone editing their profile loses the change and sees no error

My guess (optional, not checked): The save may be failing quietly

The strong one takes about five minutes longer to write, and the person fixing it can try it on a fresh account in under a minute. Notice where the guess sits. It comes last and is labelled as unchecked. If “the database isn’t saving” appears at the top, the fixer may go and look at the database before reading your steps, and your steps were the useful part.

How do you attach proof without leaking customer data?

A screenshot is the best evidence you can give, and the easiest way to leak something. Look at what is actually in the frame before you send it.

What is visibleWhy it mattersWhat to do
Customer names and emailsThey never agreed to be shared with a contractorRepeat the bug on a test account and screenshot that; otherwise cover it with a solid box, not a blur
A long address with a token in it (reset, magic link, invite)Anyone holding the link may be able to use itCrop or cover the address bar, and treat that link as spent
Card numbers, API keys, secret valuesA screenshot is a copy that lives in someone’s inbox foreverCover them, or do not capture that screen
A screen recordingNotifications and other tabs get recorded tooClose other apps and turn on do-not-disturb first
Browser console or network exportsThese can carry session cookies and tokensSend only if asked, and ask what to remove first

The cleanest fix is to reproduce the bug with a test account whose data you made up. There is then nothing private to cover, and it proves you can repeat the problem, which is the point of the report.

Where does WayRunner fit when something breaks?

WayRunner helps with two lines of that template and leaves the rest to you. You describe a flow in plain English, it drives a real Chromium browser through your connected site, and the run page lists each step with the page address and a screenshot you can click through. That is your steps and your evidence, written while the thing happened instead of from memory. If you are new to running a check from a URL, the walkthrough for Lovable, Bolt and Replit apps shows how to phrase the instruction. Run it three times and “how often” has a real answer instead of “it happened once”.

One detail from the build bears on the rule about keeping facts apart from guesses. When a step fails, a separate analysis pass reads the browser agent’s own transcript plus a screenshot and writes a one or two sentence diagnosis. It is told to sort failures into kinds: a blocking prerequisite such as a login wall or a modal, the wrong element, a disabled control, a real system error, or a false success, where the agent said it was done and the page never changed. That last kind is a good reminder for any report. Write what the page showed, not what you assumed would happen.

The diagnosis is there to help the part of WayRunner that decides each next click, the Planner, choose its next move. It is a model’s reading of a screenshot, so treat it as a lead for your “My guess” line and never as a confirmed cause.

On evidence, WayRunner blacks out password inputs in the screenshots it keeps, and that is where its redaction stops. A customer name, an email address or a number on the page is not covered, so the table above still applies to anything you copy out of a run.

The limits are plain. It is web only, in Chromium, so a bug that only happens on a customer’s phone or in an old Safari stays out of reach. It also works from a clean test account, so it cannot see the data or history that led to your customer’s bug. A passing run tells you the flow worked for the test account; it does not mean your customer imagined the problem.

A bug report is a small piece of writing with one job: let someone else see what you saw. Fill in the template, keep your guess on its own line, cover the personal data, and send one problem at a time. If you want the steps and screenshots captured while you test, instead of rebuilt from memory afterwards, try WayRunner on the flow your last bug report was about.