How to turn bug reports into Claude Code fix prompts

Claude Code and Cursor are good at changing code when you tell them what is wrong in a way they can follow. They are bad at "signup is weird, can you look?" The app you built with them will get bugs. The skill that saves your evening is turning a bug into a prompt that fixes that bug and leaves the rest alone.

This guide is that skill. It works if the bug came from your own notes, from a friend, or from a Persqo session that already drafted the prompt for you. You will learn the shape, how to tighten a messy note, and how to paste the session's prompt without letting it balloon into a redesign.

The same shape works in Lovable and Base44. Those tools are chattier, which means a vague prompt will change more of the page. A tight prompt is even more important there.

What an editor can obey

An editor can obey concrete instructions. It cannot obey a mood. A prompt it can obey usually has five parts. You do not need headings for all five if the prose is clear, but each part should be present.

1. Who got stuck, in one line. "A first-time visitor on a phone, trying to sign up."
2. Steps. The clicks, in order, starting from the public URL, signed out.
3. What happened. The words on the screen, the URL, and anything you checked, such as "no new row in the user list."
4. What should happen. One screen, one proof. "After submit, show a page that includes the email they typed."
5. The fence. What not to change. "Keep the current layout. Do not remove the email check. Do not add a payment bypass."

If a part is missing, the editor fills it in with a guess. The guess is how your signup form becomes a new hero section.

Here is the shape, filled with a made-up bug so you can see the density you want. This is a teaching example, not a transcript from a real run.

Fix the public signup for a first-time visitor on a phone.
Goal: sign up and reach a screen that shows the new account.

Steps:
Start signed out on the home page.
Tap Join.
Fill the email and the password.
Tap Create account.

What happened:
A note said "You're in" and the page returned to the home page.
The header still said Log in.
The test email never appeared in the user list.
The browser console showed a failed create request. The page did not say so.

What should happen:
Show the error on the form if create fails.
If create works, open a page that shows the account email.

Fence:
Keep the current design.
Do not remove the form.
Do not skip auth.
Do not add a way to bypass payment.

That is a whole prompt. You can paste it. You do not add "make it delightful" at the bottom. Delight is how the button moves.

From a messy note to that shape

Friends write messy notes. You write messy notes at midnight. The translation is mechanical. Do it before you paste.

Messy: "Hey the signup thing glitched on my phone, it kind of flashed and went back, maybe the server? Also the green is ugly."

Pull out only the parts the editor needs.

• Who: a person on a phone. You do not know more. Say that.
• Steps: they were on signup. You may need to ask which button, or you watch them, or you reproduce it yourself once.
• What happened: a flash, then the previous page. Ask what the flash said, or reproduce and read it.
• What should happen: they should end up signed up, with the account visible.
• Fence: do not restyle the green. The color note is a separate, optional prompt. Mixing it in is how the bug fix becomes a theme change.

If you cannot fill "what happened," reproduce the bug once in a private window and write down the sentence on the screen. A prompt without the sentence will invent one.

If several bugs arrived at once, make several prompts, or one prompt with a numbered list of findings that share a page. Do not merge a broken footer link with a signup failure. Different pages, different prompts. The editor's attention is wide. Your fence has to be the thing that narrows it.

A second translation problem is blame. "Your generator wrote a bad form" is not a step. Delete the blame. Keep the screen. The editor does not fix your feelings. It fixes the branch you described.

What a Persqo report already contains

You can write these prompts by hand. You can also start from a session that writes them for you.

You paste a URL. Persqo drafts three visitors. You edit the goals and accept once. Each visitor gets a real browser and tries the goal, including signup when that is the goal. They will not pay or send a text. The report lists findings, serious ones first. Each finding can carry a screenshot and the steps. There is a fix prompt you can copy, labeled for Claude Code and Cursor.

The prompt the product writes follows a steady shape. It tells the editor to fix the public site for a visitor like the one who ran, with that visitor's role, device, and comfort level. It states the goal. It lists the findings with their severity, the steps, and a screenshot reference when one was captured. It ends by asking for a patch so this visitor can finish the goal, without a payment bypass, and without throwing away the current design.

That is already the five parts. Your job is to read it before you paste, not to rewrite it from scratch.

Read it like an editor yourself:

• Is the goal the job you actually care about? If the draft goal was fuzzy, the prompt will faithfully chase the fuzzy goal. Fix the goal and rerun, or edit the goal line in the prompt if you are sure.
• Are the findings the blocking ones? A prompt that leads with a missing alt and a console error may bury the stuck signup. You can move the blocking finding to the top, or delete a low note from this prompt and handle it later. Do not delete the stuck step to make the prompt nicer.
• Is the fence intact? Keep the lines about the current design and about not bypassing payment. Add a fence if you need one: "Do not change the pricing page."
• Does it name a page? The steps usually include the path. If a finding is vague, add the URL you saw in the replay.

Then copy it. The button copies the prompt for Claude Code or Cursor. Paste into the chat you use for the repo. If the app lives in Lovable or Base44, paste the same text there and add the page name in the first line if it is not already obvious.

The replay is how you check the steps. Play the stuck visit once. If the prompt says the visitor clicked Join and the replay shows they clicked a footer link, correct the prompt. A wrong step sends the patch to the wrong control. Screenshots confirm you are describing the screen the editor cannot see. The replay guide is worth ten minutes before you paste a prompt you do not fully believe.

How to paste it so the fix stays small

A good prompt can still be applied badly. A few habits help.

Paste into a clean chat when the previous chat was about a different feature. Old context makes the editor "finish" work you already abandoned.

One goal per paste. If you have three visitors and only one got stuck, paste the prompt for that visitor. Do not concatenate three prompts "to save time." You will get one large diff and no idea which part fixed the goal.

Ask for the smallest change that makes the goal reachable. The product's prompt already says to keep the design. Repeat it if your tool tends to restyle: "Smallest change. Do not redesign."

If the tool shows a plan, read the list of files. A signup bug that wants to edit the pricing page, the blog, and the config is a plan to reject. Tell it to limit the edit to the signup path.

Do not accept a fix that hides the error, deletes the test, or skips the auth check. Those are the patches a vague prompt invites. The fence exists so you can say no.

When the patch is in, do not argue with the diff for long. Run the visitor again. The first guide is blunt about this: the second session is the proof. If the goal is reached, write one sentence about what changed, so the next prompt does not undo it. If the goal is stuck in a new place, write a new prompt about the new place. Do not keep replying "still broken" in the same chat with no new steps. "Still broken" has no screenshot.

A before and after

Made-up note from a friend, then the prompt you actually send.

Before: "tried to add a client on my phone and it just sat there, the plus did nothing, also can you make the list prettier, thanks!!"

You reproduce it. Private window, narrow width, signed in as a test account. You tap the plus. The URL stays on /clients. No message. A console error says a function is missing. The plus is a button with no label, only an icon.

You do not mention "prettier."

Fix /clients for a visitor on a phone who is trying to add one client.

Steps:
Sign in as a test account.
Open /clients.
Tap the plus icon at the top of the empty list.

What happened:
Nothing on the page changed.
The console reported a missing function when the icon was tapped.
The icon button has no text label.

What should happen:
Tapping it opens a way to add a client, and after save the client appears in the list.
If it fails, show a sentence on the page.
Give the icon a label a screen reader can use.

Fence:
Do not restyle the list.
Do not change the home page.

You paste that into Claude Code. The patch wires the button and adds a label. You run the same phone visitor, goal "add one client and see it in the list." The replay shows the tap, the form, the new row. You tick it. Tomorrow you may ask for prettier. Today the job works.

If Persqo ran that visitor, the report's prompt would already contain the console finding, the unlabeled control, the steps, and the screenshot. You would add the fence line about the home page if you wanted to be extra sure, then paste. Same skill, less transcription.

Prompts for the bugs that are not crashes

Not every useful fix is a stack trace. Usability bugs need the same five parts, or the editor will "fix" them by adding a tooltip nobody reads.

"The visitor never found pricing" becomes: steps from the home page, what links they had, the fact that no link says price, and the result you want, a visible way to open pricing. Fence: do not invent a price that you have not decided. Saying "add a pricing page that charges a number you just made up" is how fake prices ship. If you do not know the price, the fix is a clear sentence, or a link to a page you already wrote.

"The empty state is blank" becomes: the screenshot of the blank list, the words you want on it, and the button to the first job. Fence: only the empty state.

The guide on usability and QA helps you decide which kind of finding you are holding. The prompt shape does not change. The "what should happen" line changes. For QA, the step should complete. For usability, a specific person should be able to tell what to tap. Write that person into the first line so the editor does not optimize for you.

A small checklist before you hit paste

• One job.
• Steps a stranger could follow.
• The words that actually appeared.
• The proof you want on the screen.
• A fence around layout, payment, and unrelated pages.
• A plan to run the same goal after the patch.

Do that, and bug reports stop being a pile of chat. They become patches you can check. The session is there so you do not have to write the first draft of the prompt alone. You still read it. The paste is yours.

Questions people ask