Guide · versioned

How I evaluate AI output

A living guide. I wrote v1 in 2025 after building Launchling's evaluation framework; v2 is how I'd do it in October 2026. I've kept both, because the gap between them says as much as either version does.

In about September 2025 I wrote my first version of this guide, on how to evaluate the output of AI features, distilled from what I'd learned building an evaluation framework for Launchling. A year on, most of its instincts still hold; however, some of it now reads like a period piece, and it leaves out the lesson Launchling taught me most painfully, which is that the evaluation machinery can become harder to trust than the thing it's meant to evaluate. I've rewritten it below as v2, kept the original underneath with notes on where it has aged, and I fully expect to write a v3 before long.

Next review: Apr 2027

What changed between v1 and v2

Aspectv1 · Sept 2025v2 · Oct 2026
Where it startsWith a framework: dimensions, rubric, scoringWith the outputs: read real ones, name how they fail, then write checks for those failures
How it scores1–5 scores per dimension, overall score, optional z-scoresSpecific pass/fail checks per failure mode; scores only where a scale genuinely means something
The LLM judgeTrusted for breadth, with "periodic" manual reviewCalibrated against a small human-labelled set before it's trusted, and re-checked when anything changes
Order of workDesign the whole systemGet one case running end to end, then grow it
CostMentioned only as model comparisonTracked alongside quality from the first call
ScopeSingle outputsSingle outputs and multi-step, agentic workflows
InfrastructureBuild it yourselfUse off-the-shelf tracing and evaluation tooling for the plumbing; spend your effort on the judgement
LimitsListed as caveats at the endEvery check declares what it can't see and how it fails

Why evaluate at all

The reason hasn't changed: ordinary tests tell you whether software ran, not whether what an AI produced was any good. An evaluation should help you answer four questions, and I'd still put them exactly as I did in 2025:

  • Did that change help or hurt? (a model swap, a prompt tweak, a change to the inputs)
  • Is it safe to ship?
  • Where is quality uneven? (across user groups, scenarios or input types)
  • What are the weak points? (systematic failure modes, brittle edge cases)

What I'd add in 2026 is a fifth: what is this costing us? Quality and cost are the two things an AI product has to be able to see, and in Launchling I lost sight of both at once.

1. Get one case working end to end first

Before anything else, I'd want to be able to take one fixed input, generate or load its output, evaluate it against one rubric, write the result to a local file and exit cleanly. No database, no batch runner, no dashboard. Everything else (batches, persistence, reporting, regression alerts) is added only once that works and keeps working. In 2025 I built the platform before proving one case end to end, and spent days repairing the machinery instead of evaluating anything.

2. Look at the outputs before you write the rubric

Read a few dozen real outputs, note every way they disappoint, group those notes into failure modes, and write checks for the failure modes you actually find. Criteria you invent in advance tend to measure what you expected to go wrong rather than what does. This approach owes a lot to Hamel Husain's writing on evals and to Shreya Shankar and colleagues' research on validating LLM-based evaluators ("Who Validates the Validators?", 2024), which also shows that your criteria will shift as you read more outputs; I think that's a feature, as long as you version the rubric when it happens.

3. Prefer specific pass/fail checks to scores

"Does the plan recommend a tool the user said they can't afford?" is easier to judge consistently, and easier to act on, than "personalisation: 3.8/5". I'd keep a single overall score only where it's genuinely useful for spotting trends, and I'd stop using statistical refinements like z-scores until the basics are stable.

4. Calibrate the judge before you trust it

Using an LLM to evaluate an LLM is usually the most practical way to evaluate at breadth; however, the judge is a model too, and it needs evaluating. Label a small set of outputs yourself (or with someone who knows the domain), measure how often the judge agrees with you, and only rely on it for the checks where it does. Use a judge from a different model family to the generator where you can, because a model marking its own family's homework tends to be generous. Re-check agreement whenever you change the judge's prompt or model.

5. Version everything that could change a result

Unchanged from 2025, and still the part I'd defend hardest: model version, prompt version, input version (question set, wording, schema, third-party data) and rubric version, all recorded against every result, so that a score can be traced to exactly what produced it. A score without that context can't be reproduced or compared.

6. Enforce contracts at the boundaries, in code

v1 called for "strict schemas"; Launchling taught me that writing the schema down isn't the same as enforcing it. Define inputs, outputs and evaluation records once, in one place, validate them at every boundary, and make the pipeline fail loudly when something doesn't match. Use stable internal codes that don't change when the wording a user sees does. When different parts of a system each hold their own idea of what a record looks like, they drift apart quietly.

7. Track cost alongside quality, from the first call

Record model, input and output tokens and purpose for every call, at a single shared client layer, as an individual record rather than a running total. Make sure a usage record survives if something later in the pipeline fails, because otherwise the runs that went wrong are exactly the ones whose cost disappears. Reconcile what you've recorded against the provider's actual bill now and then. I spent days in 2025 failing to get Launchling's token usage to save reliably, and never did; I'd now treat cost visibility as a precondition for running evaluations at scale, not a nice-to-have.

8. Build synthetic data for coverage, and keep it separate

Also largely unchanged: make sure every meaningful input value (and the important combinations) appears somewhere; write personas that reflect the people you're building for, to test whether output is genuinely tailored to them; build edge-case suites (absurd-but-coherent, adversarial, ethically charged, malformed) to keep guardrails honest; and keep synthetic results apart from real ones so you never accidentally average them together.

9. Evaluate the steps, not just the answer

Much of what I build now is multi-step: agents that plan, call tools and hand work to each other. A good final answer can hide a bad route to it (an unnecessary tool call, a skipped check, a cost that ballooned), so I'd evaluate the steps an agent took as well as what it produced.

10. Report infrastructure confidence and quality confidence separately

A passing test that a mocked API response parses correctly says nothing about whether the advice was good. By the end of Launchling I was measuring progress in passing tests rather than in the quality of the product's output; I'd now report the two as separate kinds of confidence so that one can't stand in for the other.

11. Buy the plumbing, build the judgement

In 2025 I built my own logging, orchestration and reporting, with Airtable for storage. There are now off-the-shelf tools for tracing and evaluating AI applications, and I'd use them, spending my own effort on the parts no tool can supply: deciding what good looks like for these users, and checking whether the evaluator agrees.

12. Know what each check can't see, and how it fails

Every check has blind spots, and every check fails in one of two directions: closed, where it blocks everything and the product goes stale, or open, where it quietly reports that all is well. I'd decide deliberately which way each check should fail, never let a single check become a single point of failure, and ask every evaluator (human or AI) to say what it couldn't assess. Fold's review panel is built around this idea.

Caveats I'd still give

Metric gaming, selection bias, drift and overfitting to your own test set are all still real. Model outputs vary between runs, so record temperature and seeds where you can and don't over-read small differences. Synthetic data tells you about the cases you thought of; real use will always find others.

If you evaluate AI output differently, or think I've got something wrong here, I'd like to hear about it. Get in touch.

Archived · written Sept 2025 · My first version, from about September 2025. Notes marked 2026 show where it has aged. · the text was reworded in neutral terms in November 2026; dated notes sit alongside it.

Building an AI output evaluation framework

This sets out the approach I used in a personal project, which may be useful for other AI features. It's a product-oriented evaluation, not a full machine-learning or data-science approach: it's about observing whether output fits users, catching regressions and supporting future changes, and data scientists may prefer deeper statistical evaluation. It uses an LLM to evaluate the LLM, which is useful for fast and broad evaluation, but should still be calibrated with periodic manual review.

Why measure? You need a reliable way to tell whether an AI feature is doing the right thing for users, and to keep doing so as things change. An evaluation framework lets you quantify quality over time and spot regressions early. It answers:

  • Did that change help or hurt? (e.g. model swap, prompt tweak, input schema update)
  • Is it safe to ship? (i.e. as a guardrail before or after releases)
  • Where is quality uneven? (e.g. across user cohorts, scenarios or input types)
  • What are the weak points? (e.g. systematic failure modes and edge-case brittleness)

Key use cases the framework covered: prompt changes (measuring improvement and catching unexpected deterioration); model changes (comparing cheaper and pricier models and mix-and-match strategies); input changes such as question sets, schemas or third-party data (verifying downstream quality stays stable); and risk probing (testing deliberate edge cases and known weaknesses to keep guardrails honest).

What the framework evaluates. AI outputs against what good looks like for the user. In my case that included accuracy and relevance (are recommendations sound and minimal?), help alignment (does the output actually solve the user's need?), safety and tone (is it clear, inclusive and within ethical boundaries?) and overall quality (a single, comparable signal for roll-up analysis). Scoring supports both absolute metrics and relative ones (e.g. z-scores) to detect shifts even when raw scales differ across cohorts or versions.

How it works

  1. Assemble evaluation data: a fixed selection of real user inputs, plus synthetic inputs covering the full input space and meaningful combinations, persona-specific cases to test tailoring, and edge cases to stress guardrails.
  2. Version everything that matters: model, prompt, input (question set and wording, third-party data, schema) and the evaluation prompt or rubric, so scores are reproducible and comparable.
  3. Score outputs: a clear rubric with discrete dimensions, per-dimension and overall scores, optional weighting where some things matter more, and optional z-scores within a cohort or version to flag relative regressions.
  4. Analyse and compare: quality over time by version, by cohort (confidence, budget, persona, skill level), regression detection against a baseline, and the top recurring failure signatures by scenario.

Canonical fields and strict schemas. To compare like with like: canonical field codes that are stable and decoupled from interface wording, and strict schemas for user inputs (the input contract), model outputs (the evaluation contract) and evaluation records (the analytics contract). Strict validation prevents silent drift and makes version differences explicit.

Observability and analytics. Run IDs that tie every artefact to a change set; per-dimension and overall scores for drill-down and roll-up; cohort breakdowns; version diffs that isolate the impact of model, prompt or input changes; tallies of recurring issues; summary artefacts for sharing and audit.

Synthetic test strategy. Coverage (every canonical value appears, plus key pairings and triads to expose interaction effects); personas (realistic identities and constraints to test personalisation and fairness); edge suites (absurd-but-coherent, adversarial or charged, legality and ethics probes, malformed inputs); isolation (keep synthetic results separate from real traffic).

Caveats and pitfalls. Evaluator bias and leakage (a judge from the same model family as the generator will probably score optimistically); metric gaming, selection bias, drift and overfitting; how to weight synthetic against real; determinism (record temperature, seed and caching, as reruns vary); schema brittleness.

Built from: Launchling (EXP-002) · Fold's review panel (EXP-006)