I have lost count of the number of times a team has told me their Opus 5.2 workflow is “broken” and then handed me a prompt to fix. In the majority of those cases the prompt was not the primary failure point. The prompt was simply the most visible and easiest thing to blame. Real breakage more often lived in the task definition, the quality of the source material, the absence of clear success criteria, or a review step that had quietly disappeared under time pressure. The diagnostic sequence below is the one I now use before I touch a single instruction. It saves time and prevents the false confidence that comes from endlessly rewriting prompts while the actual problem remains untouched.
Why Prompt-First Debugging Usually Fails
Prompts Are the Most Visible Surface
When an output is wrong, the prompt is the artifact people can see and edit. Context quality, success criteria, and review discipline are less visible, so they receive less scrutiny. Visibility drives diagnosis even when it should not.
Rewriting Prompts Creates the Illusion of Progress
Each new prompt version produces a different output. Difference feels like improvement. Without pre-committed success criteria, teams cannot tell whether the new output is actually better or merely different. The cycle continues.
Prompt Changes Can Mask Deeper Instability
A prompt adjustment may temporarily suppress one failure mode while leaving the underlying instability untouched. The workflow looks repaired until the next slightly different input reopens the same crack.
A Diagnostic Sequence That Starts Upstream of the Prompt
Step 1: Restate the Actual Job the Workflow Is Supposed to Do
Write the intended outcome in one or two plain sentences before looking at any prompt or output. If the team cannot agree on what “done” means, the workflow is under-specified. Prompt engineering cannot compensate for an unclear job.
Step 2: Examine the Source Material Quality
Many failures originate in incomplete, contradictory, or poorly scoped inputs. If the source itself cannot support the requested output, no prompt will reliably produce it. Diagnose the material before diagnosing the instructions.
Step 3: Check Whether Success Criteria Were Written Before the First Run
If criteria were invented after seeing outputs, every subsequent judgment is contaminated. Recover the original intent if possible; otherwise pause the workflow and write criteria that can be applied consistently.
Step 4: Inspect the Review Step That Actually Occurs
On paper most workflows include human review. In practice the review is often shortened, skipped, or performed by someone without access to the source. A missing or weakened review step is a common root cause of “the model keeps making the same mistake.”
Step 5: Only Then Examine the Prompt and Context Assembly
After the job, the material, the criteria, and the review process have been checked, the prompt and the way context is assembled become useful places to look. Changes made at this stage are more likely to address real causes.
Common Non-Prompt Failure Modes I Encounter
Success Criteria That Shift After Every Output
Teams adjust what they consider acceptable based on the latest result. The target moves, so the workflow can never be declared stable. The fix is to freeze criteria for a defined test window.
Context That Quietly Loses Critical Sections
Retrieval systems drop chunks; manual context assembly forgets appendices or secondary files. The model is then blamed for missing information it never received. Logging exact context composition exposes this quickly.
Review Fatigue Disguised as Model Failure
When reviewers are overloaded they begin accepting fluent but incomplete outputs. The apparent error rate rises even though the model’s behavior has not changed. The diagnosis belongs to workload and process design, not instruction wording.
Task Scope That Exceeds What the Source Can Support
Asking for prioritization, causal explanation, or recommendations when the source only contains raw description sets the model up to invent. The failure is in the request, not in the model’s refusal to stay inside the evidence.
The following table maps frequent symptoms to the diagnostic layer that usually contains the real problem:
Observed Symptom | Most Common Actual Layer | First Diagnostic Action |
|---|---|---|
Outputs feel randomly different | Success criteria or review drift | Freeze criteria and inspect real review practice |
Model “misses” key facts | Context assembly or source gaps | Log exact context the model received |
Recommendations over-reach | Task scope exceeds source support | Rewrite the job description more narrowly |
Same error returns after prompt changes | Upstream process, not prompt | Restart diagnostic sequence from Step 1 |
Reviewers keep finding new problems | Review fatigue or unclear criteria | Measure review time and re-clarify “done” |
How to Run the Diagnostic Without Slowing the Team to a Halt
Time-Box the First Pass
A full diagnostic does not require days. A focused ninety-minute session that walks through the five steps above usually surfaces the dominant failure layer. Deeper work can follow only where evidence points.
Keep Artifacts Lightweight
Write the restated job, the criteria, and the context log in plain language. Heavy process documentation becomes another source of friction and is often ignored.
Separate Diagnosis From Redesign
First identify the layer that is actually broken. Only after that identification should redesign begin. Mixing the two produces scattered changes that are hard to evaluate.
What Changes Once Teams Stop Defaulting to Prompt Rewrites
Conversations Become More Precise
Instead of “the prompt needs work,” teams begin saying “the source cannot support causal claims” or “the review step is being skipped under deadline pressure.” Precision accelerates real fixes.
Stability Improves Faster
Because effort is applied at the actual break point, fewer cycles are wasted on cosmetic prompt variations. Measured stability across repeated runs becomes attainable sooner.
The Model Is Judged More Fairly
When upstream problems are removed, the remaining failures are more likely to reflect genuine model limitations. Those limitations can then be designed around rather than endlessly prompted against.
Closing the Diagnostic Approach
When an Opus 5.2 workflow fails, the prompt is the most convenient suspect and often the wrong one. A disciplined sequence that begins with the job definition, moves through source quality, success criteria, and actual review practice, and only then examines instructions and context assembly produces faster and more durable repairs.
Useful remains a higher bar than impressive. A workflow that is repeatedly “fixed” by prompt changes while the real break points remain untouched will never clear that bar. Diagnosing upstream is how the bar becomes reachable.
