Debugging a prompt that almost works

The 80% prompt is the hardest one to fix. You know it is wrong, but the output is close enough that you cannot immediately name what the instruction is missing. This lesson gives you three diagnostic moves that surface the missing constraint without guessing.

Why the 80% problem is hard

When a prompt fails completely, the failure is obvious. When it fails 20% of the time, you are tempted to conclude the model is unpredictable and there is nothing to fix. That conclusion is almost always wrong. The failure has a cause, and the cause is almost always a missing or ambiguous specification in the prompt.

The three diagnostic moves:

Move 1 — Read the failure, not the output

When the output is wrong, do not ask "what should the output have been?" Ask "what rule would have to be in the prompt to prevent this specific mistake?" The mistake is the diagnostic signal. A response that is too long means the prompt has no length constraint. A response that uses jargon the audience cannot understand means the prompt did not specify the audience's knowledge level.

Move 2 — Name the missing constraint

Write it in plain English before you add it to the prompt. "The output should never use bullet points — it must be prose." "The output should always end with a single action item." "The output should not include any information not present in the input." Once you can write the rule clearly, it will work in the prompt.

Move 3 — Test one change at a time

Add the new constraint. Run the same input that caused the failure. If the failure disappears, the constraint was the fix. If the failure persists, the constraint was not the cause — remove it and look for the next candidate. Never add two constraints in one round of testing; you will not know which one fixed it.

Walk-through

Take the workflow prompt you built in the previous lesson. Deliberately break it: remove one constraint. Run it on three different inputs. Find a failure. Then:

1. Write one sentence describing the failure.
2. Write one sentence stating the rule that would have prevented it.
3. Add that rule to the prompt.
4. Run the same three inputs again.
5. Confirm the failure is gone.

If the failure is gone, you have debugged the prompt. If it persists, go back to step 2.

If you get stuck

• "I can't tell what the failure is — it just feels off" — Ask Claude to critique its own output: "What is missing or incorrect in this response, given this prompt?" It will often name the constraint you forgot to include.
• "Every input produces a different failure" — Your prompt has too many variable slots and not enough structure. Add a format section that specifies the exact output shape before adding any other constraints.
• "Adding constraints makes it worse" — You are adding contradictory constraints. Read all the constraints aloud in order. If any two contradict each other (e.g., "be concise" and "cover every point"), resolve the contradiction explicitly.

Cross-reference

Once your prompt is stable, "Save what works as a Project" turns it into a persistent workspace that your teammates can use without seeing the prompt at all.

Deliverable

You have identified one specific failure in a prompt, named the missing constraint in one sentence, added it, and confirmed the failure no longer appears on the same input. The success criterion: you can run the prompt on an input that previously failed and the output is now usable without manual correction.

Further reading

• "Switch Channels, Don't Dig" — the three-strike rule: when iterating on a prompt that's almost working stops being productive, the answer is usually a different channel, not a tighter constraint.