Reading fifty failures

The highest-value hour in applied AI

Sit down with fifty failures. Read each one. Write one line saying why it failed. Then group the lines.

That is the whole technique, it takes about ninety minutes, and it will change what you work on next more than any other activity in this course. Teams that do it routinely stop guessing; teams that do not spend months rewriting prompts against problems that were never prompt problems.

The reason it works is the distribution. Failures are never spread evenly across twenty causes. Three causes are usually 60 to 80 per cent of them, and you cannot see which three from a summary metric.

Do it in this order

1. Take failures, not a random sample. You are diagnosing, not estimating a rate. Fifty is plenty; twenty is enough to see the big clusters.

2. Write the cause in your own words, before naming a category. “Only the first page of the receipt was in the input”, not “extraction error”. Free text first. Categories imposed too early hide the thing you did not expect.

3. Cluster afterwards. Sort the fifty lines, merge the ones that say the same thing, count.

**4. Assign each cluster an owner and a kind.** This is the step that pays. Kinds:

• Data: the input was wrong, missing, or not what the system was given.
• Retrieval: the information was not supplied.
• Prompt: the instruction was ambiguous or absent.
• Model: the instruction was clear and it did not comply.
• Label: the expected answer was wrong. It happens more than teams expect.
• Product: the request was reasonable and the system is not designed to serve it.

What it looks like

A receipt-extraction system, 50 failures:

• 22: multi-page receipts, only page one uploaded. Data. The mobile client sent one image. No prompt change would have helped.
• 11: dates read as MM/DD when written DD/MM. Prompt. One sentence naming the locale convention, plus a deterministic check that the parsed date is not in the future.
• 8: illegible photographs. Product. The answer is to detect blur and ask for a retake, not to extract harder.
• 5: totals wrong because a discount line was subtracted twice. Model. Real, and the smallest cluster.
• 4: miscellaneous.

The team had been comparing three prompt variants for a fortnight. Two of the three top causes were not in the prompt at all, and the biggest one was a client bug. That is the typical shape of this exercise, not a dramatic example chosen to make a point.

Turn the clusters into a taxonomy

Write the cause names down and reuse them. Tag every future failure with one. Within two months you have a chart of failure causes over time, and it answers the question no pass rate can: what is going wrong now, and is it the same thing as last month?

A cluster that keeps reappearing after a fix was shipped means the fix did not work, which is exactly the fact that a stable overall score conceals.

Cheap tricks that speed it up

• Sort failures by input length, language, or slice tag before reading. Clusters often fall out of the ordering for free.
• Cluster automatically for a first pass. Embed the failure outputs with a free local model, run k-means with k around 8, read three items per cluster. This is a way to find candidate groups quickly, not a substitute for reading. The names you get from reading are better than the ones you get from a centroid.
• Diff against a run that passed. For items that used to pass and now fail, put the two outputs side by side. The cause is usually visible in seconds.
• Keep the fifty. They become eval items with an origin field, which is the subject of a later lesson.

The rule

No prompt change without error analysis first. It sounds bureaucratic and it is the opposite: it is what stops you spending a fortnight on the 10 per cent cause while the 44 per cent cause sits in a client bug nobody has looked at.

And it is the part of this work that does not automate. A model can cluster your failures; it cannot notice that the receipts are all from one chain whose printer cuts off the total. That noticing is the job.