Diagnosing the failure before choosing the fix

Thirty failures, sorted by cause

Nobody fine-tunes because of a hypothesis. They fine-tune because something is wrong and fine-tuning is the most impressive-sounding thing to do about it. The cure is dull: collect thirty real failures, sort them by cause, and count.

Thirty is enough because you are not measuring a rate, you are finding out which kind of problem you have. If twenty-two of thirty land in one bucket, the decision is made. If they scatter evenly across six buckets, you do not have a model problem, you have a product that has not been specified.

The six causes, and the test for each

Format. The content is right and the shape is wrong: prose where you wanted JSON, three bullet points where you wanted five, a stray preamble before the answer. Test: run a schema validator over the output and separately ask a person whether the content is correct. If the validator fails and the person says the content is fine, it is a format failure.

Knowledge. The model does not know a fact about your world. Test: the paste test: put the missing document into the prompt and ask again. If it now answers correctly, the model was never short of ability, only of information.

Style and register. Correct content in the wrong voice: too chatty, too hedged, American spelling in a British document, an apology on the front of every reply. Test: rewrite one output by hand. If your rewrite changes no facts, it is style.

Capability. Multi-step arithmetic, long-horizon planning, a hard inference. Test: give the identical prompt to the largest model you can reach. If the frontier model also fails, you are not going to add the capability with two thousand examples and a rank-16 adapter. Training teaches a model to produce answers of a shape it can already produce.

Instruction adherence. The model satisfies four of your seven constraints and drops the rest, usually the ones stated earliest. Test: count satisfied constraints per output and plot against the number of constraints in the prompt. If the satisfaction rate falls as constraints rise, it is adherence, and this is one of the places fine-tuning shines.

Cost or latency. The outputs are fine. The bill is not, or the p95 is 4.2 seconds and your product needs 800 milliseconds. Nothing about quality is broken.

The labelling loop

CAUSES = ["format", "knowledge", "style", "capability", "adherence", "cost"]

for row in failures:            # 30 rows, read in a text editor is fine
    print(row["prompt"][:400])
    print("---")
    print(row["output"][:400])
    row["cause"] = input("cause? ")   # one label, the thing you'd fix FIRST

One label per item. Failures overlap (a badly formatted answer to a question the model could not have known is both) so the rule is: label it by what you would have to change first. If you fixed the knowledge and the format problem would still be there, label it knowledge.

What each cause actually wants

• Format → constrained decoding first. A grammar or a JSON schema at sampling time makes invalid output impossible rather than unlikely, and it costs nothing to try. Fine-tuning for format works, but it only makes the bad output rarer.
• Knowledge → retrieval. Weights are a poor filing cabinet; the next lesson in this module is entirely about this.
• Style → five examples in the prompt, then, if the style is long or subtle enough that the examples eat your context budget, fine-tuning. Style is the cause fine-tuning fixes most reliably.
• Capability → a bigger model, or decomposition into steps each of which the small model can do.
• Adherence → fine-tuning. A model trained on a thousand examples that all respect your seven constraints learns the constraints as a habit rather than as instructions competing for attention.
• Cost → distillation. Not a quality problem at all, and the one place where fine-tuning is unambiguously the right tool.

Where people get stuck

The commonest mislabel is knowledge as capability. A model that confidently invents your refund window looks stupid, and stupidity feels like a capability problem. Run the paste test before you believe that. The second commonest is style as adherence: “it ignores my instruction to be concise” is usually a style failure, because the model has a strong prior about how long an answer should be and your one word is arguing with millions of training examples.

The limitation of this whole exercise is that thirty failures are the failures you noticed. Silent failures (plausible, wrong, unreported) are invisible to it, and they are usually knowledge failures. So treat the sorted counts as a map of your complaints, not of your quality.