You asked Claude Code to “fix the timezone bug in invoice rendering.” The PR comes back beautifully — well-tested, well-documented, and entirely about cache invalidation in the invoice list. It’s a real bug it found while reading the file. It’s not the bug you asked about. The timezone issue is still there.
Output-vs-prompt divergence almost always happens during plan formation, not during code generation. Claude reads the prompt, the file, related context, then commits to a mental task that drifts from what you wrote. By the time the code lands, the plan is already wrong — and the code reflects the plan faithfully. The fix: force an explicit restate-before-execute step so you catch the divergence at the cheap stage.
Common causes
Ordered by hit rate, highest first.
1. The prompt was ambiguous and Claude picked a plausible interpretation
“Fix the timezone bug” could mean: the rendering bug, the storage bug, the parsing bug, or the comparison bug. Claude saw the first one it ran into and proceeded. You meant a different one.
How to spot it: After the work, look at your original prompt with fresh eyes. If you can identify 2+ valid interpretations, ambiguity was the cause.
2. Claude skimmed a long prompt and missed the key sentence
Long prompts (>200 words) sometimes get summarized into “the main ask” — your secondary constraints or specific framing drop out. Claude works from the summary.
How to spot it: The work matches the first major instruction in your prompt but ignores conditions added later (“but make sure it doesn’t break the email path”).
3. CLAUDE.md primed a competing default
Your prompt said “do X.” CLAUDE.md says “we always do Y in this area.” Claude reconciled by doing X-in-the-style-of-Y, which isn’t what you wanted.
How to spot it: Output matches a CLAUDE.md convention you forgot was there, even though your prompt specified differently.
4. Claude inferred intent from file context, not the prompt
You said “fix the bug.” Claude read invoice.ts, saw an obvious code smell, decided that was the bug, and “fixed” it. The actual bug was in a different file.
How to spot it: The diff is in a file you didn’t name and didn’t expect to touch.
5. Claude solved a related, easier problem
You asked for the harder fix. Claude saw an easier related issue, fixed that, and called it done. Common when the real fix needs deeper investigation than Claude wanted to do.
How to spot it: The change is small and clean for a problem you were prepared to spend hours on. Suspicious.
6. The prompt described the symptom, Claude addressed a different cause
“Users see wrong timestamps” — could be timezone, formatting, server clock, browser locale, DB column type. Claude picked one cause, fixed it, but the actual cause was another.
How to spot it: Bug is still reproducible after Claude’s “fix.” The reported symptom didn’t pin down which root cause.
Shortest path to fix
Ordered by ROI. Step 1 catches 80% of misalignment at the cheap stage (planning), not the expensive stage (code).
Step 1: Force a restate-before-execute step
Add to every non-trivial prompt:
Before any tool use:
1. Restate the task in 3 bullets:
- What I'm asking you to do (one sentence)
- What success looks like (one observable criterion)
- What is OUT of scope (what you will NOT touch)
2. List 2 alternative interpretations of the prompt you considered and rejected.
3. Wait for my confirmation before proceeding.The “alternative interpretations” line is the lever — it forces Claude to surface ambiguity instead of silently picking.
Step 2: For bug fixes, demand the failing reproduction first
Before fixing:
1. Reproduce the bug. Show me the exact input that triggers it + the exact wrong output.
2. Trace the failure to the responsible code with file:line.
3. Propose the fix.
4. Wait for my approval before writing code.This catches “fixed the wrong bug” because you see the reproduction before the fix.
Step 3: For multi-step tasks, get a status update after each step
After each step (file changed / test added / migration applied):
- Paste a one-line summary
- Stop and wait for "proceed"
- Do not start the next step until I confirmYou can interrupt mid-task instead of finding misalignment at the end.
Step 4: When divergence happens, diagnose at the plan, not the diff
If output doesn’t match intent, don’t just fix the code — figure out where the misread happened:
Your output is correct code for X. I asked for Y.
Walk me through:
1. What did you understand the task to be?
2. What in my prompt led to that understanding?
3. What signal would have led you to interpret Y instead?The answers improve your next prompt.
Step 5: Use a structured prompt template for non-trivial work
Goal: [one sentence]
Acceptance: [one observable criterion]
Scope: [files allowed]
Out of scope: [files/concerns NOT to touch]
Constraints: [must / must not]
Context: [domain info Claude can't infer]A 6-line template eliminates most ambiguity-driven misreads.
Step 6: For repeat divergence, sharpen the prompt category
If similar prompts keep going wrong (“fix bug” → fixes wrong bug), the pattern is the prompt category. Make a per-category template:
prompts/fix-bug.md
prompts/add-feature.md
prompts/refactor.mdEach has the structured layout above, calibrated for that category. Reuse instead of re-typing.
Prevention
- Restate-before-execute is non-negotiable for non-trivial work
- For bug fixes, require the failing reproduction before the fix proposal
- Use structured prompt templates per category (bug, feature, refactor)
- Get per-step status updates so divergence is interruptible
- When divergence happens, diagnose the plan (not the diff) and update the prompt category
- A 5-line specific prompt beats a 50-line ambiguous one — specificity > length