Module 11 · Lesson 05

Diagnosing Failure — Why Prompts Go Wrong

Reading time: 14 minutes Track: Claude Fluency for Teams · Required for all learners

Failure diagnosis is a skill

When a Claude output doesn't meet expectations, the instinct is to blame the model or try the same prompt with different words. Neither approach is efficient. Diagnosing the actual failure mode takes 30 seconds and points directly to the fix.

The six root causes of prompt failure

Failure Mode 1: Insufficient context

Symptom: Output is generic or makes assumptions that don't fit your situation. Cause: Claude doesn't know enough about your specific context. Fix: Add the specific context that was missing. Ask yourself: "What would a new hire need to know to do this task well?"

Failure Mode 2: Ambiguous task specification

Symptom: Claude does something related to but not exactly what you wanted. The output is beside the point. Cause: Your task description allowed multiple interpretations; Claude chose a different one than you intended. Fix: Use a specific verb and describe the exact output, not the goal. "Write X" not "help with X". "List Y" not "tell me about Y".

Failure Mode 3: Missing format specification

Symptom: Content is right but format is wrong — too long, wrong structure, wrong tone. Cause: No format specification was provided. Fix: Be explicit: "respond as a numbered list", "under 150 words", "use a table with these columns".

Failure Mode 4: Constraint violation

Symptom: Claude does exactly what you asked, but violates an implicit assumption you had. Cause: You had constraints in your head that you didn't write down. Fix: Document your constraints. After any output that violates a constraint, add that constraint explicitly.

Failure Mode 5: Factual error / hallucination

Symptom: Output contains specific facts that are wrong. Cause: Claude generated plausible-sounding content it doesn't actually have accurate data for. Fix: Point out the specific error. Add "I will provide all factual data you should rely on" and supply the primary sources. Or explicitly ask Claude to flag where it's uncertain.

Failure Mode 6: Instruction conflict

Symptom: Claude seems confused, addresses some constraints but not others, hedges constantly. Cause: Your prompt contains conflicting requirements ("be concise" + "cover all aspects comprehensively"). Fix: Prioritize your requirements. Tell Claude explicitly: "Prioritize brevity over comprehensiveness."

The 60-second diagnosis workflow

When an output misses, before you refine:

1. What exactly is wrong? (Tone, content, format, facts, focus?)
2. Which failure mode does this match?
3. What's the specific fix?

This takes 60 seconds and prevents the common mistake of adding more and more to a prompt without addressing the actual problem.

Prevention: the pre-flight check

Before sending an important prompt, a quick scan:

• Have I given enough context? (Would a smart new hire have enough to go on?)
• Is the task specific? (Does a single interpretation exist?)
• Have I specified format and length?
• Have I written out my constraints?
• Are there any conflicting requirements?

This 30-second check prevents the most common failures.