Room 42, home

Fix a prompt that is not working

A repeatable loop for diagnosing a bad result and tightening your prompt until Claude gives you what you want, every time you run it.

Promptingintermediate7 min readUpdated 13 Jun 2026

In short

  1. 01Fixing a bad prompt is a loop: read the result, name one gap, change one thing, run again, and stop when it passes twice.
  2. 02Sort the failure into wrong facts, wrong format, wrong scope, or wrong reasoning, and each bucket points at one specific fix.
  3. 03Change only one variable per run so you learn what actually helped, and add missing context before you tune wording.
  4. 04Lock the win by moving durable rules into a CLAUDE.md file, and use /rewind to roll back when a change makes things worse.
Contents · 9 sections
  1. 1The loop in one diagram
  2. 2Why is my prompt giving the wrong result?
  3. 3Step 2: name exactly one gap
  4. 4Step 3: change one thing, then run again
  5. 5Step 4: lock the win so it sticks
  6. 6What if a fix makes things worse?
  7. 7A worked example
  8. 8What should you not do when fixing a prompt?
  9. 9Checklist

When a prompt gives you the wrong thing, do not rewrite it from scratch and do not add the word "please." Run a loop instead: read what you got, name the single gap between that and what you wanted, change one thing, and run it again. Repeat until the result is right twice in a row. This page teaches that loop with Claude and the Claude Code CLI.

The loop in one diagram

The discipline is the "one thing" rule. If you change three parts of the prompt at once and the output improves, you do not know which change helped, so you cannot repeat it. Change one variable per run and you learn something every time.

Why is my prompt giving the wrong result?

Read the output before you touch the prompt. The first instinct is to edit it. Resist that. Read the output you got and compare it line by line to what you wanted. The fix is almost always written in the gap between the two.

Sort the failure into one of four buckets. The bucket tells you which lever to pull.

SymptomWhat it usually meansLever
Right shape, wrong factsModel lacks the source materialAdd context
Right facts, wrong formatOutput target is unstatedConstrain the format
Wandered off the taskInstruction was buried or vagueMove the ask, sharpen it
Confident and wrongTask needs reasoning it skippedAsk it to think first

If you cannot pick a bucket, the result is not the problem yet. Ask Claude to tell you what it thought you wanted.

Try this prompt
Before you change anything, restate the task in your own words and list every assumption you made. I want to find where your reading of the request differs from mine.

A mismatch in that restatement is the bug. You found it without editing a single instruction.

Step 2: name exactly one gap

Write the gap as a single concrete sentence. "It is bad" is not a gap. "It returned a paragraph when I needed a JSON array of objects" is a gap. "It invented a function called getUserToken that does not exist in the file" is a gap.

A named gap maps to a specific edit:

  • Wrong facts → the source was missing, so add it.
  • Wrong format → the target was unstated, so state it.
  • Wrong scope → the boundary was loose, so draw it.
  • Wrong reasoning → the steps were skipped, so require them.

If you find yourself listing three gaps, you have three runs ahead of you, not one. Fix the gap that blocks everything else first. A format problem rarely matters while the facts are still wrong.

Step 3: change one thing, then run again

Each lever below is one change. Apply one, run, and read the new result against the same wanted output.Common gotchaThe one-thing rule covers the prompt, but the failed run is still sitting in the conversation, and that history is a hidden second variable: the model may self-correct from its own earlier mistake rather than from your edit, so a "fix" that only works mid-thread breaks the moment you start clean.Re-test each change in a fresh context (or /rewind the conversation only) so you are measuring the prompt, not the chat that preceded it.

Lever: add the missing context

A model cannot cite a file it never saw. If the facts are wrong, the source is usually absent. In the Claude Code CLI you attach a file with an @-mentionIn Claude Code, typing @ followed by a path attaches that file's contents to your message so the model reads the real code instead of guessing. so Claude reads the real code instead of guessing.

Try this prompt
@src/auth/session.ts @src/auth/session.test.ts The test on line 40 fails. Fix the session logic. Do not change the test.

This is the most common single fix. Vague results are often a context problem wearing a prompt-wording costume.Common gotchaAttaching a file is not the same as the model using it. If the source is huge or the wrong file, the answer still guesses while you assume it read the truth.Ask it to quote the exact lines it relied on, so a context gap shows up as a missing quote instead of a confident wrong fact. See context engineering for how to fill the window with exactly what the task needs.

Lever: constrain the format

If the content is right but the shape is wrong, state the shape. Show the exact structure rather than describing it.

Try this prompt
Return only a JSON array. Each item has these keys: { "path": string, "issue": string, "line": number } No prose before or after. If there are no issues, return [].

A worked example of the output beats three sentences describing it. Pin one good example with few-shot prompting and the model copies the pattern.

Lever: draw the scope boundary

If Claude edited files you did not mention or solved a bigger problem than you asked, the boundary was loose. State what to touch and what to leave.

Try this prompt
Only edit src/checkout/total.ts. Do not change tests, types, or other files. If the fix needs a change elsewhere, stop and tell me instead of making it.

The "stop and tell me" clause turns silent over-reach into a question you can answer.

How do I make Claude reason before it answers?

Confident, wrong answers usually skip a step the task needed. In the Claude Code CLI, the keyword think in your prompt allocates more reasoning budget before the model answers, and stronger keywords raise that budget further.

Try this prompt
Think about the edge cases in this date parser before you write code. List the cases you will handle, then implement.

The escalation ladder is think, then think hard, then ultrathink for the deepest budget. Reach for a stronger keyword when the problem is tangled, not for routine edits, since more reasoning costs more tokens and time.

Step 4: lock the win so it sticks

A prompt that worked once is not reliable. Two things make a one-off fix durable.

How do I know my prompt fix is reliable?

Run the working prompt on the same input a second time, and ideally on a second similar input. If both pass your check, the prompt is reliable. If the second run drifts, you fixed the example, not the prompt, and a constraint is still missing. A model produces a range of outputs for the same input, so one good result is a sample, not a guarantee.

Move durable rules into a memory file

If a constraint matters for every task, do not retype it each turn. Put it in a CLAUDE.md at the repo root. Claude Code loads that file at the start of every session, so the rule applies without you pasting it again.

# Project rules
 
- Never edit files outside the directory I name in my request.
- When you finish a change, run the test command and paste the output.
- Match the existing code style in the file you are editing.

Keep this file short. Every line is read on every turn, so a stale rule is noise the model still weighs. See rules and memory files for the full pattern.

What if a fix makes things worse?

Sometimes the fix breaks more than it solves. The Claude Code CLI checkpoints your code and conversation before each edit, so you can roll back instead of fighting forward from a bad state.

Type /rewind to open the checkpoint menu, or double-tap the Esc key to reach the same list. Pick a point and choose what to restore.

Restore choiceWhat it does
Code onlyReverts file edits, keeps the conversation
Conversation onlyRewinds the chat, leaves files as they are
BothReturns code and chat to the chosen point

One caveat: /rewind reverts file edits, not external side effects. A git push, a package install, or a network call already happened and will not be undone. Checkpoints are automatic per prompt and persist across sessions, with old ones cleared after roughly thirty days.

Rewind to the last point where the result was right, then run the loop again with one smaller change.

A worked example

You ask for a summary of a config file and get a wandering paragraph that misnames two settings.

Two changes, one per run, each tied to a named gap. You never guessed. By run three you have a prompt you understand and can reuse, and you confirmed it by running it twice.

What should you not do when fixing a prompt?

  • Do not add "please be accurate" or "do not make mistakes." These add tokens and change nothing. The model was already trying.
  • Do not rewrite the whole prompt after one bad run. You throw away the parts that worked and learn nothing.
  • Do not stack five constraints at once before testing any of them. Add the one the current gap needs.
  • Do not accept the first good result as proof. Run it again on a fresh input.
  • Do not paste a summary of an error. Paste the full error text. The detail you cut is often the clue.

Checklist

Before you decide a prompt is fixed:

  • Did you read the actual output against the wanted output, not just skim it?
  • Can you name the single gap in one concrete sentence?
  • Did you change exactly one thing this run?
  • Did the working prompt pass twice, on two inputs?
  • Did durable constraints move into CLAUDE.md so they apply next time?
  • Do you know which change fixed it, so you can do it again?

A prompt that passes this list is not lucky. It is debugged, and you can explain why it works.