What you will be able to do
- Trace a weak Claude output back to the gap in the prompt that caused it: missing context, ambiguous instruction, absent constraint or wrong strategy for the task type
- Tell missing context apart from an absent constraint by what the faulty output looks like
- Run a diagnosis loop that changes one diagnosed cause at a time and checks the result against the same list of shortfalls
- Choose the least disruptive fix that matches the gap: a follow-up, a fresh prompt, or a different strategy
Key concept
Specification gap — A specification gap is something the prompt failed to tell Claude that the task needed: the situation, a clear instruction, a limit on the output, or the right method for this kind of task. Diagnosis means naming which of these was missing, because each one has a different fix.
1.Weak output usually points back to the prompt
When a Claude draft misses the mark, start by looking at what the prompt left out. Claude starts every task like a capable new hire on their first day. It knows a lot in general and nothing about your client, your deadline or your house style. Anything the prompt doesn't say, Claude has to guess, and the output shows where those guesses landed. A generic paragraph, a made-up figure or a format nobody asked for is usually the visible end of something the prompt didn't specify.
A quick way to find the gap is the colleague test. Hand the prompt to a coworker who knows nothing about the task and ask them to carry it out. If they would need to ask what the client was told, how long the piece should be, or who will read it, Claude needed those answers too. It didn't ask. It filled them in. For the parts of a prompt that should be present to begin with, see prompt construction. This lesson starts after a prompt has already failed.
Not every shortfall is a specification gap, though. If the output is accurate and well-shaped but arrives too slowly or costs too much, the fix may be outside the prompt altogether, such as choosing a different model (model and effort selection). Diagnosis comes first so that you know which kind of fix to reach for.
Checkpoint 1 of 7· Check yourself
A team reviews four disappointing Claude results. Which one is least likely to be fixed by revising the prompt, and points instead to a fix such as choosing a different model?
Invented figures, generic text and unrequested formats usually show something the prompt left unspecified. Output that is accurate and well-shaped but too slow or too costly is not a specification gap, so the fix may be outside the prompt, such as choosing a different model.
“For example, you can sometimes improve latency and cost more easily by choosing a different model.”Source: platform.claude.com
2.Four kinds of gap and the symptoms of each
Each kind of gap leaves a recognisable mark on the output, and reading that mark is most of the diagnosis. The table pairs each gap with its usual symptom and the first fix to try.
| Gap | What the output looks like | First fix |
|---|---|---|
| Missing context | Generic or boilerplate substance, placeholders where facts should be, or confident figures that were never supplied | Add the real situation: the facts, audience, goal and how the output will be used |
| Ambiguous instruction | A reasonable answer to a different question, or the bare minimum when you wanted more | Say exactly what you want, in steps if order matters, and why |
| Absent constraint | Right substance, wrong shape: too long, wrong format, over budget, outside a restriction you never stated | State the limit explicitly: word count, format, structure, requirements |
| Wrong strategy for the task type | Clear, complete instructions still give inconsistent edge cases or shallow multi-stage work | Switch method: add examples, chain the stages, or ask Claude to reason first |
Missing context is the most common gap. Take an account manager who types "Write a follow-up email to the client about the delay." They meant a five-day supplier delay, a new delivery date and a 10% credit for a long-standing client, but they never wrote any of it down. The email that comes back apologises for an "unforeseen issue" because that phrase is all Claude can say without the facts. Giving Claude a role wouldn't fix this. A role shapes behaviour and tone, but it supplies no facts. Tone guidance wouldn't fix it either, because the problem is that the email has nothing to say, not how it says it. The deliverable was clear: a follow-up email. The same reasoning covers a commentary on quarterly revenue requested with no figures shared. However you reword the request, Claude has no data, so the numbers it produces are invented. More context fixes that. Rewording doesn't.
Absent constraint looks different. The substance is right, but the output breaks a limit that existed only in your head. A 600-word answer when you needed 150, or a bulleted list when the text goes into a formal letter, means a constraint was missing, not context. Context describes the situation, such as who the audience is and what the goal is. A constraint limits the output, such as word count, format or timeline. Asking "would knowing more about the situation have fixed this?" separates the two. If the answer is no, a limit was missing.
Ambiguous instruction includes instructions that are written down but hard to find. Picture a 600-word prompt full of company background and a customer persona, with "Avoid technical jargon" in the middle of the third paragraph. If the draft comes back full of jargon, the instruction was lost among the context. Pull instructions, context and examples into their own XML-tagged sections, then give the reason behind the rule (the readers are non-technical shoppers). Claude can apply a reason to cases the rule never named. Writing the rule in capitals is less effective than explaining why it matters.
Wrong strategy is the diagnosis to make once the specification is complete. Suppose a support lead's category definitions are clear and thorough, yet tickets that mix a billing question with a login error are labelled differently from batch to batch. More definition won't help. Borderline cases are learned from examples, and the examples should be diverse enough to cover edge cases. Likewise, a task with several real stages that comes back shallow from one prompt calls for a different structure, not a longer prompt.
Checkpoint 2 of 7· Match them up
Each draft below came back weak for a different reason. Match each specification gap to the symptom it most likely caused.
Tap a term, then the definition that fits it.
Facts that were never supplied, so Claude used placeholders or invented them, point to missing context. Right substance in the wrong length or format points to a missing limit. A rule lost among background text is an ambiguous instruction. Inconsistent edge cases despite a complete specification call for a different method, such as diverse examples.
“Clear constraints (word count, format, timeline)”Source: claude.com
Checkpoint 3 of 7· Exam question
An account manager types into a new Claude chat: "Write a follow-up email to the client about the delay." The email comes back generic, apologizes for an unnamed "unforeseen issue", and offers nothing concrete. The manager had meant to explain a five-day supplier delay to a long-standing retail client, give the new delivery date, and offer a 10% credit, but none of this appeared in the prompt. What is the best diagnosis?
Correct answer: A — Missing context: the prompt named the task but gave Claude none of the real situation, so it filled the gaps with boilerplate wording.
- A. Correct. Claude can only work from what is in the conversation. The prompt stated the task but none of the facts about the delay, the new timing or the offer, so Claude produced a plausible but empty email. The fix is to supply those facts.
- B. Incorrect. Tone guidance would change how formal or warm the email sounds, but it cannot make Claude produce a supplier cause, a delivery date or a credit offer it was never given. The missing material is factual content, not voice.
- C. Incorrect. A role could shape the perspective and style of the email, but Claude would still have no cause, date or credit to write about. Assigning a persona does not replace facts the prompt left out.
- D. Incorrect. The request to write a follow-up email to the client about the delay was clear, and Claude produced exactly that kind of email. What it lacked was the content to put into it, not clarity about the deliverable.
3.A diagnosis loop that changes one cause at a time
Diagnosis only works if you can tell afterwards which change helped. That depends on a clear statement of what success looks like and a way to check the output against it. Without those, every revision is a guess, and a better draft can't be credited to anything. Most of the method follows from that:
- Compare the output with what you needed and write down each concrete way it falls short. "Doesn't give the new delivery date" is a shortfall. "Feels weak" is not.
- Trace each shortfall to a gap in the prompt: missing context, unclear instruction, absent constraint or wrong strategy for the task type.
- Revise only the part of the prompt tied to that gap, and leave the parts that already worked alone.
- Run the revised prompt and check the new output against the same list of shortfalls to see whether the gap closed.
Step 3 is where people usually go wrong. Rewriting the whole prompt after one bad draft changes several things at once. If the next draft is better, nobody knows which change did it. If it is worse, a part that used to work may have broken. Changing one thing works like a small A/B test: the earlier version is the baseline, and the new version is judged against the same criteria. Step 4 uses the same list rather than a fresh impression so the comparison stays honest. A draft can feel better overall while the gap you set out to close is still there.
As a new shortfall with its own diagnosis. Length is a limit on the output, so this is an absent constraint. Add a word limit and leave the context you just added unchanged.
Checkpoint 4 of 7· Check yourself
After a client email comes back without the new delivery date, an analyst rewrites the whole prompt. They add a persona, reorder the sections, include the delay facts, set a word limit and paste in three sample emails. The next draft is better. What is the main weakness of this revision?
Revising only the part tied to the diagnosed gap (here, missing context) turns each revision into a small A/B test against the earlier version. Changing everything at once means a better draft can't be credited to any one change. A role supplies no facts, and the new draft should be checked against the same list of shortfalls, not a fresh impression.
“A/B testing: Compare performance against a baseline model or earlier version.”Source: platform.claude.com
Checkpoint 5 of 7· Exam question
A manager has a weak Claude draft and wants to change the prompt only where the evidence supports it, one diagnosed cause at a time, so they can tell what worked. Which sequence should they follow?
Correct answer: C — List how the output misses the need → Trace each miss to a prompt gap → Change the prompt part tied to the gap → Rerun and check against the miss list
- A. Tracing gaps before listing shortfalls is misplaced. Without a concrete list of how the output falls short of the need, the manager has no evidence for judging which prompt wording is a gap, so they would diagnose on a hunch.
- B. Changing the prompt before tracing each shortfall to a gap is misplaced. The edit would not be tied to a diagnosed cause, so the manager could change parts that already worked and could not attribute any improvement to a specific fix.
- C. The manager first names the concrete shortfalls against the need. Then they attribute each one to a prompt gap, change only the part tied to that gap, and rerun against the same shortfall list to see whether it closed.
- D. Listing the shortfalls after the gaps were traced and the edit made is misplaced. The diagnosis and the change then rest on an impression of what is wrong, and the list is written after the fact instead of grounding the diagnosis.
4.Iterate, restart or change approach
Once you know the gap, pick the least disruptive fix that addresses it. Move to a bigger fix only when the smaller one has failed for that same reason. There are three levels, and each fits a different situation.
Iterate in the same chat when the draft is close and the gap is local. If one section of a customer FAQ has the wrong tone, a follow-up that names that section and asks for it to be rewritten keeps everything that already works. Follow-up instructions, clarifications and requests to rewrite are the normal way to refine a response.
Restart with a fresh prompt when the same problem survives several follow-ups. At that point the gap is in the original specification, not in one section, and the draft was built on that gap from the start. Open a new chat, restate the full requirements and add the missing context. A well-built prompt can get there in one go, where a poor one needs repeated back-and-forth.
Change approach when a complete fresh prompt still fails because of the kind of task it is. The usual changes are:
- Add examples when the format or style is easier to show than to describe, or when simple instructions keep giving inconsistent results. Start with one example and add more only if the output still misses.
- Chain prompts when the task has several real stages. Each prompt handles one stage and passes its output to the next, which costs time but makes each step easier and more accurate. Sequencing is covered in task decomposition.
- Look outside prompting when the problem is speed or cost rather than quality.
When a prompt finally works, save it so the next person doesn't have to repeat the diagnosis. Turning it into a reusable template is a repeatable workflow task, and it comes after the fix, not before.
Checkpoint 6 of 7· Check yourself
A marketing lead has sent three follow-ups asking Claude to make a product announcement "more specific". Every draft is still vague about the launch, because the original request never included the launch details. What is the best next step?
The same problem survived several follow-ups, so the gap is in the original specification: missing context. The next step is a fresh prompt that restates the requirements and adds the missing facts. Chaining or examples come only if a complete fresh prompt still fails because of the kind of task it is, and neither one supplies the missing launch details.
“A poorly structured prompt might require multiple back-and-forth exchanges to clarify intent, while a well-engineered prompt gets you there in one shot.”Source: claude.com
Checkpoint 7 of 7· Exam question
A manager's first prompt for a customer FAQ produced a draft that is close, but the tone in one section is off. The team applies the least disruptive remedy that matches the diagnosed gap and escalates only when the earlier remedy has failed for that same reason. Which sequence of actions should they try?
Correct answer: D — Ask for a rewrite of the off-tone section → Restart in a fresh chat with full requirements → Split the work into chained stage prompts → Save the working prompts as a template
- A. Restarting in a fresh chat before trying a targeted follow-up discards a draft that is mostly right. It is a larger change than the single off-tone section requires, and escalation is only justified after the smaller remedy has failed for that same reason.
- B. Splitting the work into chained prompts before trying a fresh restart skips a lighter remedy. Chaining is warranted only when evidence shows one prompt cannot carry a multi-stage task, and no such evidence exists yet when the restart has not been tried.
- C. Chaining the work first is the heaviest change and is applied before any evidence of failure, and the targeted follow-up is delayed. The scenario describes one off-tone section in a near-finished draft, so a stage-by-stage rebuild is far out of proportion.
- D. A targeted follow-up is the cheapest fix for a draft that is mostly right, and a fresh restart comes only after repeated failure. Chaining is the heaviest change, and the template is saved last because it only exists once something has worked.
Sources
(6)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practicesOfficial docs
“Key test: Show your prompt to a colleague with minimal context on the task and ask them to follow it.”
↩︎ Weak output usually points back to the prompt“Setting a role in the system prompt focuses Claude’s behavior and tone for your use case.”
↩︎ Four kinds of gap and the symptoms of each“XML tags help Claude parse complex prompts unambiguously, especially when your prompt mixes instructions, context, examples, and variable inputs.”
↩︎ Four kinds of gap and the symptoms of each“Diverse: Cover edge cases and vary enough that Claude doesn’t pick up unintended patterns.”
↩︎ Four kinds of gap and the symptoms of each“Think of Claude as a brilliant but new employee who lacks context on your norms and workflows.”
↩︎ Key concept“Providing context or motivation behind your instructions, such as explaining to Claude why such behavior is important, can give Claude more information”
↩︎ Exam trap 2“explicitly request it rather than relying on the model to infer this from vague prompts”
↩︎ Prediction - 2.
“Not every success criterion or failing eval is best solved by prompt engineering.”
↩︎ Weak output usually points back to the prompt“you can sometimes improve latency and cost more easily by choosing a different model”
↩︎ Weak output usually points back to the prompt“Some ways to empirically test against those criteria”
↩︎ A diagnosis loop that changes one cause at a time“For example, you can sometimes improve latency and cost more easily by choosing a different model.”
↩︎ Checkpoint - 3.https://claude.com/blog/best-practices-for-prompt-engineeringSecondary source
“Clear constraints (word count, format, timeline)”
↩︎ Four kinds of gap and the symptoms of each“Relevant context (who's the audience, what's the goal)”
↩︎ Four kinds of gap and the symptoms of each“A poorly structured prompt might require multiple back-and-forth exchanges to clarify intent, while a well-engineered prompt gets you there in one shot.”
↩︎ Iterate, restart or change approach“Simple instructions haven't produced consistent results”
↩︎ Iterate, restart or change approach“This approach trades latency for higher accuracy by making each individual task easier.”
↩︎ Iterate, restart or change approach“Start with one example (one-shot). Only add more examples (few-shot) if the output still doesn't match your needs.”
↩︎ Exam trap 4 - 4.
“Building a successful LLM-based application starts with clearly defining your success criteria and then designing evaluations to measure performance against them.”
↩︎ A diagnosis loop that changes one cause at a time“A/B testing: Compare performance against a baseline model or earlier version.”
↩︎ A diagnosis loop that changes one cause at a time - 5.https://support.claude.com/en/articles/7996857-my-prompt-isn-t-giving-me-a-helpful-answerOfficial docs
“Give Claude feedback: you provide Claude with follow-up instructions, clarifications, or ask it to rewrite an answer.”
↩︎ Iterate, restart or change approach“Make sure that your prompt contains as much context as possible.”
↩︎ Exam trap 3
Also cited
“It doesn’t have any context about you, your task, or your organization.”
↩︎ Exam trap 1