Prompt Iteration: Diagnosing and Fixing Prompts That Are Not Working

The issue: You wrote a prompt. The output is not what you needed. You are not sure whether to rephrase, add context, start over, or give up. Most guidance covers how to write a good prompt from scratch; less attention goes to diagnosing a prompt that has already failed. This is a different skill — reading the output for signals about what went wrong, and deciding what kind of fix will actually address the root cause.

The three root causes of bad output

Almost every disappointing response traces to one of three problems. Identifying which one you have determines what to do.

1. Claude misunderstood the task. The output is coherent and confident but addresses a different question than you asked — a broader version, a related version, or a version that makes sense from the outside but not from inside your project. The response is not wrong, it is just not yours.

Signal: Technically correct but generically so. Could have been written for any researcher with a vaguely similar question. Does not use your terminology or engage with your specific material.

2. Claude had the wrong context. Claude understood the task but worked from incomplete or misleading information. Your expected answer was in the prompt. An irrelevant document was included. The CLAUDE.md was outdated. The task was given without the source it needed.

Signal: Output reflects your framing back at you, or misapplies conventions from a different part of the project, or confidently fills in gaps with plausible-sounding invented content.

3. The task was not bounded well enough. Claude did something — but the output varies across sessions, or different parts of a long output apply different interpretations, or the response addresses a mix of things rather than one thing precisely. The problem is not Claude's execution; it is the task definition.

Signal: Output is internally inconsistent, or the task would produce different results if you ran it again, or you cannot tell from the output whether it succeeded.

Reading the response for diagnostic signals

Before rephrasing or starting over, read the output specifically for what it reveals about Claude's interpretation:

What did Claude add that you did not ask for? If Claude explains something you already know, it underestimated your expertise — add audience framing. If it addresses a broader question than yours, the task was underbounded — add specificity.

What did Claude omit that should have been there? If a required section is missing, the task did not specify it clearly enough. If the source material you provided is barely referenced, Claude either did not read it carefully or had so much other context that it dominated.

Where does the output hedge? Hedging ("it is difficult to say", "there may be") can signal that Claude recognized it was operating beyond its knowledge — check whether you asked for something it genuinely cannot know, or whether missing context would resolve the uncertainty.

Does the output sound like you? If the voice, framing, and conclusions match your prior notes, you probably included too much of your own interpretation alongside material that should have been read fresh. The output is synthesis rather than independent analysis.

Is the output length and register right? Too long usually means the task was underbounded (Claude filled in what it thought you wanted). Too short usually means the task was overbounded (strict constraints left no room). Wrong register (too formal, too informal, too technical for your audience) means the audience was not specified.

The fix decision: iterate or restart

Iterate when the problem is small and local — a missing constraint, an unclear verb, a context gap that a single addition will fix. One targeted correction, not a rewrite.

Restart when:

The most common mistake is iterating when a restart is needed. Three rounds of "actually, what I meant was..." produce an output that is more influenced by your corrections than by the source material. When you notice yourself explaining what you really wanted, stop and start a new session with a better-bounded prompt.

Targeted fixes for common failure patterns

Output is correct but generic — does not engage with my specific project

Fix: Add the specific material explicitly. Claude may not have read CLAUDE.md as carefully as you assumed, or the task was not connected to the project context.

[Original task], but specifically for [your project]. Refer to the context in CLAUDE.md.
Focus on [specific source/question/constraint].

Output confirms what I already thought — feels like my view back at me

Fix: Restart. Remove your hypothesis from the prompt entirely. If you described your expected findings, your prior analysis, or why this matters to your argument, all of that should come out.

[New session] Read [source]. What is its central argument about [topic]?
Do not tell me whether it supports [hypothesis] — I will assess that after reading your summary.

Output is technically correct but applies wrong conventions or wrong format

Fix: Specify the constraint you omitted. The format, citation style, output structure, or field-specific convention was not stated and Claude used its default.

Same task, but output as [specific format]. Use [specific convention].

Output varies unpredictably across different runs

Fix: The task is underbounded. Add a success criterion — what a correct output looks like — and the decision rule for ambiguous cases.

[Task]. A correct entry looks like: [example]. If you encounter [ambiguous case], [do this].

Output for a long task went wrong partway through

Fix: Decompose. Identify where the task diverged and run that stage separately with an explicit verification point.

The meta-prompt technique

When you are not sure why an output failed, ask Claude to explain its own interpretation before you try to fix it:

Before I give you feedback: in two sentences, state what you understood the task to be
and what the main decision you made in producing this output was.

This costs thirty seconds and often reveals the misunderstanding immediately. You can then correct the interpretation rather than guessing at which part of the prompt produced it.

Alternatively, use this as a preventive step on any task where a misread would be costly:

Before starting: state in two sentences what you understand the task to be,
what the output will look like, and what you will do if you encounter an unclear case.
Then proceed.

When the prompt is not the problem

Not all bad output is a prompting failure. Sometimes the issue is:

Iterating on a prompt that is addressing the right task, with the right material, in a fresh context will usually converge within two rounds. If it does not, the problem is probably in one of the categories above.

Related