Stop Hand-Tuning Prompts. Let Your Eval Set Do It.

A client asked me to look at their support-triage prompt because it had stopped improving. The prompt was eleven hundred words long. It had a dozen rules bolted on over six months, three of them contradicting each other, and a comment at the top that said "do not touch the ordering, it breaks returns." Nobody remembered why. Every time accuracy dipped, an engineer added another sentence, eyeballed twenty cases, and shipped. They had no record of what they had already tried and no way to know if the new version was actually better or just better on the five examples they happened to look at that afternoon.

This is how most prompts are still written in production. By hand, one guess at a time, with the judgment of whoever is on call that day and no memory between attempts. It is the one part of the stack we somehow decided should stay artisanal while everything around it got a test suite and a pipeline. The result is a prompt that nobody can safely change, drifting quality, and an engineer's afternoon burned every time the numbers move.

There is a better loop, and it has gotten genuinely good in the last year. You already have the two things it needs: an eval set and a way to score a run. Point an optimizer at both and let it do the tuning that your engineer was doing by hand, except it remembers every attempt, scores against the whole set, and keeps only what actually wins.

The real problem is not the prompt, it is the process

Hand-tuning fails for reasons that have nothing to do with how good your engineers are. A prompt is a point in an enormous space of possible wordings, and a human can test maybe five or ten points before they run out of afternoon. You cannot hold the last twenty variants in your head, so you re-test things you already rejected. You judge on whatever handful of cases you scrolled past, which means you optimize for the loud failures and never see the quiet regressions your change introduced on the other side of the distribution.

And the cost is not just the hour you spent. It is the hour the next person spends being afraid to touch your prompt, the accuracy you leave on the table because nobody dares refactor the eleven-hundred-word mess, and the silent regression that ships because the person tuning it looked at returns and never noticed they broke refunds.

The fix is to treat the prompt the way you treat any other artifact you cannot verify by eye. You define what good means with a metric, you let a search find candidates, and you keep the winners. The search does not get tired, does not forget, and scores every candidate on the entire eval set instead of the five cases that fit on screen.

Reflective optimization, in one paragraph

The naive version of automated prompt search is to mutate the prompt randomly and keep whatever scores higher. It works, slowly, and it burns a fortune in eval calls. The modern version is smarter: instead of mutating blindly, you show a model the prompt, the cases it got wrong, and why they were marked wrong, and you ask it to rewrite the prompt to fix those specific failures. The model reflects on the feedback in natural language and proposes a targeted edit. This is the idea behind GEPA, the reflective optimizer that landed at ICLR 2026, and the headline result is the one that matters for a budget: it reaches a better prompt in far fewer rollouts than reinforcement learning, because a paragraph of "here is what went wrong and why" carries vastly more signal than a single reward number.

That last point is the whole game. If your metric only returns a score, the optimizer is searching in the dark. If your metric also returns a sentence explaining the score, the optimizer can reason about the failure and write a prompt that addresses it. So the first real work is not the optimizer. It is a metric that explains itself.

Step one: a metric that gives feedback, not just a number

Here is a scoring function for a classification task. Notice it returns both a score and a human-readable reason, because the reason is what a reflective optimizer actually learns from.

from dataclasses import dataclass

@dataclass
class Eval:
    score: float          # 0.0 to 1.0, what the optimizer maximizes
    feedback: str         # WHY it got this score; this is the signal

def score_triage(example, prediction) -> Eval:
    """Score one support-triage prediction and explain the score.

    `example` carries the gold label; `prediction` is the model's output.
    The feedback string is written for another model to read, so it names
    the mistake concretely instead of just saying 'wrong'.
    """
    if prediction.category == example.gold_category:
        return Eval(1.0, "Correct category.")

    # A wrong answer is not just wrong; say how, so the optimizer can fix it.
    return Eval(
        0.0,
        f"Predicted '{prediction.category}' but the correct category is "
        f"'{example.gold_category}'. The ticket mentions "
        f"'{example.trigger_phrase}', which should route to "
        f"'{example.gold_category}', not billing. The current prompt likely "
        f"over-weights the word 'charge'.",
    )

The billing detail is invented for the example, but the shape is the point. A metric that says 0.0 teaches the optimizer almost nothing. A metric that says "you confused a charge dispute with a billing question because the prompt over-weights one word" teaches it exactly what to rewrite. Spend your effort here. Everything downstream is only as good as this feedback. For a RAG prompt that means the metric has to include a faithfulness check against the retrieved source, or the optimizer will happily learn to write confident answers the documents do not support.

Step two: the optimization loop

If you use DSPy, the loop is already built and tuned, and you should start there rather than writing your own. The GEPA optimizer is available directly, and it wires your feedback metric into a reflective search for you.

import dspy

# The program whose prompt you want to optimize. In DSPy this is a module
# with a signature; the instruction text is what gets rewritten.
triage = dspy.Predict("ticket -> category")

# GEPA needs a metric that returns a score AND textual feedback, plus a
# (usually stronger, cheaper-to-be-wrong) model that does the reflecting.
optimizer = dspy.GEPA(
    metric=gepa_metric,                       # wraps score_triage above
    auto="light",                             # search budget: light/medium/heavy
    reflection_lm=dspy.LM("openai/gpt-4.1"),  # reads failures, rewrites prompt
)

# train drives the search; val selects the winner on data the search is
# scored against but does not get to memorize case by case.
optimized = optimizer.compile(triage, trainset=train, valset=val)

optimized.save("prompts/triage.optimized.json")  # the artifact you ship

The output is not a model. It is a prompt, saved to a file, that you can read, diff, and check into git like any other config. That property matters more than it looks: a reflective optimizer produces human-legible instructions, so a senior engineer can still read the final prompt and veto anything that looks like it games the metric rather than solving the task.

If you are not on DSPy, the mechanism is small enough to run yourself, and writing it once is worth it for understanding what the library does. Keep a Pareto front of candidates rather than a single best, because a prompt that wins on refunds and a prompt that wins on billing may combine into something that beats both.

def optimize(seed_prompt, trainset, reflect, run, score, rounds=8, beam=4):
    """Framework-free reflective prompt optimization.

    reflect(prompt, failures) -> new prompt   (a model rewriting the prompt)
    run(prompt, example)      -> prediction    (one inference call)
    score(example, pred)      -> Eval          (the feedback metric above)
    """
    # Each candidate is (prompt, mean_score). Start with the seed.
    pool = [(seed_prompt, evaluate(seed_prompt, trainset, run, score))]

    for _ in range(rounds):
        parent, _ = max(pool, key=lambda c: c[1])  # expand the current best

        # Collect the cases this prompt got wrong, WITH their feedback text.
        failures = [
            (ex, score(ex, run(parent, ex)))
            for ex in trainset
        ]
        failures = [(ex, ev) for ex, ev in failures if ev.score < 1.0]
        if not failures:
            break  # nothing left to fix on the train split

        # The reflection model reads the failures and proposes a rewrite.
        child = reflect(parent, failures)
        child_score = evaluate(child, trainset, run, score)

        # Keep the pool small; drop the weakest so cost stays bounded.
        pool.append((child, child_score))
        pool = sorted(pool, key=lambda c: c[1], reverse=True)[:beam]

    return max(pool, key=lambda c: c[1])  # (best_prompt, best_score)


def evaluate(prompt, dataset, run, score):
    scores = [score(ex, run(prompt, ex)).score for ex in dataset]
    return sum(scores) / len(scores)

Two things make this cheap enough to run on a real budget. The reflection model only sees the failing cases, not the whole set, so the expensive reasoning scales with mistakes rather than with data. And you evaluate candidates on minibatches during the search and only run the full eval set on the few that survive. That is how a loop like this beats brute-force search by an order of magnitude on cost.

Step three: gate it in CI so a regression cannot ship

An optimized prompt is still just a candidate until it proves itself on data the optimizer never selected against. The discipline that makes this safe is the same one you already use for model changes: optimize on train, select on validation, and prove the final number on a held-out test split you touch exactly once. Then make the comparison a build step.

# ci/check_prompt.py: fails the build if the candidate is not a clear win.
import json, sys

CHAMPION = json.load(open("prompts/triage.champion.json"))
CANDIDATE = json.load(open("prompts/triage.optimized.json"))

# Run both on the held-out TEST split (never seen during optimization).
champ = run_eval(CHAMPION, test_split)      # -> {"accuracy": .., "cost": ..}
cand  = run_eval(CANDIDATE, test_split)

# A win has to clear a margin, not just win by noise, and must not cost more
# per correct answer. Tune the margin to your eval set's variance.
MARGIN = 0.01
improved = cand["accuracy"] >= champ["accuracy"] + MARGIN
no_pricier = cand["cost_per_correct"] <= champ["cost_per_correct"] * 1.05

if improved and no_pricier:
    print(f"PROMOTE: {champ['accuracy']:.3f} -> {cand['accuracy']:.3f}")
    sys.exit(0)

print(f"REJECT: acc {champ['accuracy']:.3f}->{cand['accuracy']:.3f}, "
      f"cost/correct {champ['cost_per_correct']:.4f}->{cand['cost_per_correct']:.4f}")
sys.exit(1)

Now the prompt is a first-class artifact. The champion lives in git, the optimizer proposes a challenger, CI runs both on a split neither was tuned on, and the challenger is promoted only if it clears a real margin without getting more expensive per correct answer. This is the same muscle as gating any other change on evals, and if you have not built that harness yet, start with evals in CI to catch regressions before you automate the optimization on top of it. The optimizer is the easy part; the gate is what keeps it honest.

The parts that bite

Optimizers overfit, and they are good at it. A search that only ever sees your training examples will cheerfully learn their surface quirks, like a keyword that happens to correlate with a label in your sample but not in the wild. The train, validation, and test separation above is not bureaucracy, it is the only thing standing between you and a prompt that scores beautifully and fails in production. And the eval set itself has to keep up with reality, because a prompt optimized against last quarter's tickets is tuned for a distribution you no longer serve. Pull fresh failures from production on a schedule, which is the whole argument for a living eval set built from production traces.

Watch the metric for things it rewards that you did not mean. If your score comes from an LLM judge, the optimizer will find and exploit every bias that judge has, because exploiting the judge is literally what you told it to maximize. A prompt that learns to flatter the grader instead of solving the task will post a great number and a worse product. Calibrate the judge before you optimize against it, the same way you would before trusting it for anything else, and read the winning prompt with your own eyes to catch gaming that the score misses. I wrote about keeping an LLM judge honest for exactly this reason.

Reflection is not free either. The reflection model runs many times over a search, and a heavy budget on a large eval set adds up fast, so start with a light budget and only widen it when the gains justify the spend. If you run a fleet of agents, record that budget in the agent registry that tracks owners and budgets, so the optimization spend is attributed to someone rather than showing up as an unexplained line. And the whole loop assumes your scoring is stable enough to compare two prompts, which means pinning temperature and sampling during evaluation so you are measuring the prompt and not the dice. If your eval numbers wobble by more than your promotion margin between identical runs, fix that before you trust any ranking the optimizer produces.

The takeaway

Hand-tuning a prompt is a human doing badly, from memory, the one job in your stack that a search does well: try a change, measure it against everything, keep it only if it wins. You already own the hard parts, an eval set and a metric, so the move is to stop editing prompts by feel and start treating the prompt as an artifact that an optimizer proposes and your CI gate approves.

Write a metric that explains its scores, point a reflective optimizer at your training split, select the winner on data it never saw, and gate the promotion on a real margin that does not cost you more per correct answer. Do that and the prompt stops being the fragile file nobody will touch and becomes the thing that quietly improves every time you feed it fresh failures. The engineer who used to burn an afternoon guessing gets that afternoon back, and the quality moves on purpose instead of by luck.

If your prompts are still tuned by hand and you are not sure your last change was an improvement or just a different set of bugs, that is the pattern worth fixing first. Book a consultation call and we can stand up a feedback-rich eval set, wire a reflective optimizer to it, and put a CI gate in front of it so your prompts get better on every run and never regress into production.