The order that saves time
- Reproduce exactly. Record model ID or version, prompt revision, settings, input, retrieved passages, tool calls, and output.
- Check availability. Was the necessary fact, document, permission, or tool result actually present?
- Identify the layer. Separate generation from retrieval, OCR, parsing, schema, tool, policy, and interface errors.
- Shrink the case. Create the smallest failing input and a nearby passing input.
- Choose the matching control. Add evidence, validation, a narrower scope, deterministic code, a permission check, or human escalation.
- Run the regression set. Confirm the fix helps the target case without breaking an adjacent one.
Changing the prompt first can hide the actual defect. If the retriever never returned the decisive paragraph, more forceful wording cannot make it available. If the calculator receives a string in the wrong unit, better prose cannot correct the arithmetic path.
Common patterns and matched controls
| Observed failure | Likely layer | Control to test |
|---|---|---|
| Plausible unsupported fact | Evidence boundary or generation | Require source-backed claims, an explicit unknown state, and entailment review. |
| Correct source exists but answer misses it | Retrieval or document parsing | Inspect chunks, OCR, filters, permissions, query, and ranking. |
| Malformed JSON | Output contract or parser | Use schema-constrained output where supported and validate before use. |
| Wrong total | Calculation path | Move arithmetic to code and test units, rounding, and missing values. |
| Action taken for the wrong user | Authorization | Enforce identity and tenant checks outside the model. |
| Great demo, weak production results | Evaluation set | Replace cherry-picked examples with representative and difficult cases. |
| Quality changes without a code release | Dependency drift | Pin what can be pinned; log aliases, corpus, tools, and prompt versions. |
| Retries create duplicate writes | Workflow state | Use idempotency keys and reconcile external state before retrying. |
Use contrasts, not anecdotes
A single failure is a lead. Pair it with a nearby passing case to expose the boundary. If a document extraction fails on scanned PDFs but passes on digital text, the relevant difference may be OCR rather than model reasoning. If a classifier fails only when a required field is absent, the acceptance rule may need an explicit “insufficient information” class.
Keep a compact suite of normal, difficult, missing, conflicting, and adversarial cases. Record expected outcomes before running the system. When a failure becomes important, add it to the suite so the same defect cannot quietly return.
Measure the whole task
Request-level accuracy can obscure operational failure. Track accepted-result rate, edit time, retries, latency, tool errors, review burden, and consequential false positives or false negatives. A cheaper model that needs three attempts and heavy review may cost more per useful result than a higher request price suggests.
A useful incident note
Observed: what happened, without interpretation.
Expected: the acceptance rule and expected state.
Environment: model/version, prompt, settings, tools, corpus revision, account/region, date.
Layer: generation, retrieval, parsing, tool, permissions, interface, or unknown.
Minimal case: smallest failing input plus nearby passing input.
Fix and trade-off: change made, risk introduced, and rollback.
Regression: cases run and metrics before/after.
The fastest troubleshooting move is often to stop asking the model why it failed and inspect the system state that produced the answer.
This page represents the report’s failure-mode catalogue, diagnostic order, drift, cost, automation, and regression guidance. It converts the source table into an operational field note without claiming incidents we did not observe.