Diagnosing an Underperforming Prompt
"The output isn't very good" is a symptom, not a diagnosis. Name exactly what's wrong before touching the prompt: wrong tone, missed a requirement, invented a fact, inconsistent structure between runs.
- Try the prompt against a real input.
- Notice precisely where the output falls short — not that it's "bad," but the specific shortfall.
- Adjust with one targeted change aimed at that shortfall, then re-run the loop.
- Resist rewriting the whole prompt from scratch after one bad output — a prompt that's 90% working needs a targeted fix for the failing 10%, not a full replacement.
Asking Claude to diagnose itself: paste the underperforming prompt *plus* one or two concrete bad outputs, and ask Claude to explain the likely cause and suggest a targeted fix. Without a real failing example attached, a generic "make this better" gives Claude nothing to diagnose against — it guesses the same way you were.
Same pattern for non-writing tasks: a schema, workflow, or form only improves against real constraints (what entities exist, what relates to what, what must never be null or duplicated) — not a generic "make it more professional" ask.
Adjusting Based on Feedback — Do's and Don'ts
| Do | Don't |
|---|---|
| Fix a small set of test cases (3–5) and a consistent success rule before adjusting anything | Vary the test inputs between the old and new version "to keep things realistic" |
| Run old and new versions against the exact same inputs and rule | Declare victory after one anecdotally better-looking output |
| Note a borderline case, then apply the same standard to both versions anyway | Loosen or tighten the success criteria mid-comparison |
| Change the test set deliberately, between full evaluation cycles | Change what's being tested casually, mid-comparison |
Why it matters: if the test cases or grading standard shift between versions, a measured difference could reflect the change in testing rather than the actual prompt change. A single good run only shows the change *can* help — not that it *reliably* helps across the inputs the workflow actually needs to handle.
The Troubleshooting Decision Checklist
Work through in order — earlier items are cheaper to rule out than later ones.
| Symptom | Likely Cause | Fix |
|---|---|---|
| Generically toneless, inconsistent, guessing at an unstated standard | Vague instruction, missing role/explicit criteria | Add a concrete role and explicit rules — not more prose describing desired quality in the abstract |
| Format or structure inconsistent across runs despite detailed instructions | Missing worked examples | Add worked examples — showing the exact pattern beats describing it |
| A specific claim, figure, or citation turns out to be wrong | Unverified fact | Check against a source, or have Claude show its calculation / cite the source line and flag uncertainty |
| Output under-delivers on a genuinely complex or high-stakes task (or overkill on a simple one) | Wrong model or effort level for task demands | Match model/effort to task complexity and stakes |
| None of the above fit, and the thread has run a long time | Conversation has drifted or lost track of earlier instructions | Start fresh with a clean, well-structured prompt |
Worked example: a weekly sales summary is well-organized and consistently formatted, but states a wrong growth percentage. Rules out vague-instruction and missing-examples (structure and format are fine) — lands on unverified fact. Fix: verify the number or have Claude show its calculation. Not a role rewrite, not a model swap, not a fresh conversation.
Exam trap: a scenario naming one specific, checkable failure often pairs with a distractor answer proposing an unrelated, plausible-sounding fix borrowed from a different checklist category (switching models, adding examples, rewriting the role, starting over).
Workflow Efficiency Levers
Getting a workflow right once is different from making it cheap and low-friction to run every week. Four levers, once the workflow already works:
| Lever | What It Removes |
|---|---|
| Reusable Project | Re-explaining role, rules, and reference material (style guide, policy, schema) in a fresh conversation every run — set it once in Project instructions and knowledge base files |
| Prompt template | Re-deciding how to phrase a recurring request each time — save the message shape with placeholders for what varies |
| Right-sized model choice | Paying top-tier cost on every run — use a faster/lighter model for routine, human-reviewed, low-stakes runs; reserve the most capable model for high-stakes runs (client-facing, legal, financial) |
| Front-loaded instructions | A correction sent by hand after every run — fold anything you find yourself repeating ("include the date," "shorter," "don't forget the disclaimer") into the Project instructions or template itself |
Exam traps: using the most capable model for every run of a routine, reviewed workflow "to be safe" ignores real stakes and pays a recurring cost. Re-writing the same context from scratch each run "to keep things fresh" is exactly the repeated effort a Project eliminates. A correction repeated more than once signals it belongs in the standing instructions, not in a one-off follow-up message.