Guides / Prompting and shipping

How to Write a Good Bug Report (for AI or a Developer)

Write bug reports that get fixed the first time: a clear title, exact steps, expected vs actual result, the error message, environment and a screenshot.

Mythex Team · 2026-09-29 · 5 min read

A good bug report lets someone else — a developer or an AI — see the same problem you saw, without asking you anything. It needs a specific title, the exact steps to reproduce it, what you expected, what actually happened, any error message copied word for word, and where it happened: which page, browser, device and user. One bug per report, with a screenshot if it helps.

Most bugs take longer to understand than to fix. A clear report removes the understanding part. This matters even more with AI tools: an AI can't ask a follow-up question about what you meant by "checkout is weird", so it guesses — and a wrong guess can break something else.

The template

Copy this and fill it in:

Title: [What's wrong, where] — e.g. "Booking form rejects times after 6pm"

Steps to reproduce:
1. ...
2. ...
3. ...

Expected: [what should happen]
Actual: [what happened instead]

Error message: [exact text, if any]
Where: [page/URL, browser, device, logged in as which user]
How often: [every time / sometimes / once]
Screenshot or recording: [attached]

The rest of this guide explains each part.

Step 1: Reproduce it first

Before writing, try to make the bug happen again. You'll learn which steps matter, and whether it happens every time.

• Start from a clean state: refresh, or log out and in.
• Note each click and each thing you type.
• Try to find the shortest path that triggers it.
• Try a second browser or account. If it only happens for one user, that's a big clue.

For more on this, see how to debug an AI-built app.

Step 2: Write a specific title

The title should say what's wrong and where, so someone scanning a list knows which bug it is.

Step 3: List exact steps

Number them. Be literal: which page, which button, what you typed.

1. Log in as a customer (test account: customer@example.com).
2. Add the "Starter kit" to the cart.
3. Enter the discount code WELCOME10 and click Apply.
4. Click Checkout.

"Try checking out with a code" leaves out the details that often matter: which user, which product, which code, whether it was applied first.

Step 4: Expected vs actual

This is the core of the report. Say both, because the difference is the bug.

• Expected: The checkout page opens with the 10% discount shown in the total.
• Actual: The button shows a spinner for a second, then nothing happens. Without a discount code, checkout works.

Without "expected", the reader might not know the behaviour is wrong. Without "actual", they don't know what to look for.

Step 5: Copy errors exactly

Error messages are the fastest route to the cause. Copy them as text, word for word — don't paraphrase.

Where to find them:

• On screen: any message the app shows.
• Browser console: open developer tools (F12, or right-click → Inspect) and look at the Console tab for red lines.
• Network tab: in developer tools, find the failing request and note its URL and status code (for example POST /api/checkout → 500).
• Server logs, if you have access.

A line like TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 often points straight at the problem.

Step 6: Add context

• Where: the page URL, the environment (preview, staging or live).
• Who: which user or role — admin, member, logged out.
• Device and browser: "Safari on iPhone" vs "Chrome on Windows" can matter.
• Data: anything unusual about the record — very long text, special characters, a large number of items.
• When it started: "after yesterday's change to discount codes" is gold.
• How often: every time, or once in ten tries.

Step 7: Show it

A screenshot with the problem circled, or a short screen recording, removes ambiguity — especially for layout bugs. If your AI tool accepts images, attach one. Crop out anything private, including keys and other people's data.

Writing bug reports for an AI builder

The same structure works as a prompt. Two additions help:

• Say what must not change, so the fix doesn't cause a new problem.
• Ask it to verify the fix, not just write it.

Logged in as a customer, with the "Starter kit" in the cart and the code WELCOME10 applied, clicking Checkout does nothing. Expected: the checkout page opens with 10% off the total. Actual: a brief spinner, then nothing. The network tab shows POST /api/checkout returned 500. Checkout without a code works. Find the cause and fix it without changing how prices are calculated for orders with no code. Then check checkout with a percentage code, a fixed-amount code and no code.

If you're unsure of the cause, ask for a diagnosis first:

Don't change code yet. Based on this report, what are the likely causes, and what would confirm each one?

Common mistakes

• "It's broken." No steps, no expected result, nothing to act on.
• Several bugs in one report. Some get fixed, others get lost.
• Paraphrased errors. "Some undefined thing" hides the useful part.
• Missing the user or role. Many bugs only affect admins, or only new users.
• Only describing the fix you want ("add a null check") instead of the problem.
• Sharing secrets in screenshots or pasted logs.

Checklist

• I reproduced the bug and found the shortest steps.
• The title says what's wrong and where.
• Steps are numbered and literal.
• Expected and actual are both stated.
• Error messages are copied exactly, with any failing request and status code.
• Page, environment, user, device and browser are included.
• I said how often it happens and when it started.
• A screenshot or recording is attached, with private data removed.
• One bug per report.

Reporting bugs to Mythex's agent

In a Mythex project, the report is the prompt. A few features help:

• Attach a screenshot of the preview or error screen — up to 5 files per message.
• /fix focuses the agent on fixing a bug; Plan mode lets it investigate before editing.
• /test has the agent reproduce flows in the preview itself and report what it sees.
• Revert to this point undoes a fix that made things worse.

The docs' debugging with prompts page uses the same steps / expected / actual structure. For the fix-and-check loop around it, see how to iterate on an AI-built app.