Eval

Ordinary software tells you plainly whether a change worked. The login button either logs you in or it doesn't, so a regression test sorts every change into pass or fail and the question is settled. A regression test is an automated check that runs after a change to confirm the existing features still behave.

Features built on a large language model (LLM) slip out of that frame. Summarize the same meeting notes twice and you get two slightly different paragraphs, and neither one is wrong. With no single correct answer to match against, there is nothing to compare for equality, and pass-or-fail stops working.

So every round of prompt engineering produced the same argument. A prompt is the written instruction telling the model what to do and how. The engineer who rewrote it says it's much better now; the product manager runs two of her own documents through it and says it looks worse to her. Each side is holding two or three examples, neither can convince the other, and nobody finds out who was right until a customer complains a month later.

An eval exists to pull that judgment out of the example fight. You choose the cases in advance and freeze them in a file, and whatever you change, you rerun that same frozen set and compare scores. The prompt or the model moves; the ruler stays put.

One eval has three parts: the list of inputs to feed the model, the answer expected for each input, and the scoring method that turns a response into a number.

1. The inputs — the actual cases you send to the model. For Pagedeck's meeting-notes summarizer, that's forty real sets of raw notes.
2. The expected answers — what counts as correct for each input. Writing out a full model answer is usually impractical, so most evals list the facts the response has to contain, like "must state that the deadline was set to March 20."
3. The scoring method — the rule that compares the response against the expectation. Teams mix three: a machine checking whether a required number or phrase appears, a person reading the response and rating it, and another model grading the output against the expectation. The early ones cost almost nothing and run in seconds; the later ones cost time or money and catch differences the cheap ones can't see.

Fill the set with easy cases and it stops doing its job. Scores land near 95 every time, so the needle never moves no matter what you change. Cases that actually failed are the reliable ones, because you already know the feature can get them wrong. Every time a customer reports a bad answer, or someone inside the company hits a strange one, that input and the answer it should have produced go into the set.

Most teams start somewhere between thirty and a hundred cases. At ten, a single case flipping swings the score by ten points and you can't read the difference. At a thousand, nobody can keep up with the human grading.

If the feature uses retrieval-augmented generation (RAG), pulling in internal documents to answer from, there's a second thing to score. Alongside the answer you check whether the documents it cited were the right ones. That's how you catch a plausible answer written from the wrong source.

The person who picks the cases is the person who knows what the feature has to be good at. At Pagedeck, Mia writes the raw notes and the expected points, and Theo runs the set and reports the score. Reverse that order and the set usually goes soft: engineers pick inputs that are convenient to handle, and the messy meeting notes that tripped up an actual customer never make it in.

Three groups read the result.

1. The person who made the change — the engineer reruns the set before shipping a new prompt or model. If the score drops, the change doesn't go out.
2. The person deciding what ships — the number gets used in the room where a feature is approved. "Can we open up summaries?" answered with "the eval is at 82" at least puts everyone on the same number.
3. Whoever inherits it later — six months on, the person who takes over the feature reads the eval to learn what it's supposed to do well. The file of expected answers ends up serving as the functional spec.

"Let me run the eval first. If the score drops, this prompt isn't shipping."

Looking better to the person who wrote it doesn't count; the frozen set decides.

"Did you add that case to the eval? Otherwise we'll get it wrong the same way next time."

A bug you found once leaks out again unless it's registered in the set.

"We only have twenty cases, so I wouldn't trust this score difference."

Too few cases to tell a real improvement from luck.

This is the conversation around Pagedeck's summarizer whenever the prompt changes. Theo edits it, runs the forty-case set, and posts the new score next to the previous one. Even when the total goes up, he opens any case that went down and reads the response side by side with the old one. Averages hide changes that improve most inputs while quietly degrading one kind of meeting notes.

Mia looks past the number at what's missing. If a case from a support ticket still isn't in the set, she asks for that before anything else.

The most common mistake is reading the eval score as the quality of the feature. Hear 82 and it sounds like eight out of ten users are satisfied. What the number actually says is how forty cases you chose scored under rules you wrote. Choose different cases and the same feature scores 60 or 90. Carry that number outside the team to compare against another team or another product and you've started a contest that the most generous case selection always wins.

Assuming the set keeps working once it's built is the other one. It's a file, so it looks less perishable than code. But when the product changes, the expected answers change with it. Decide that summaries should contain only decisions and every expectation written under the old policy becomes a wrong standard. Left alone, the eval starts grading a product that no longer exists, and each false alarm teaches the team to ignore the warning. Once that habit sets in, the day hallucinations genuinely spike, that alarm gets ignored too.