{{ p.title }}

Ask a recommender why it chose what it chose, and most of them go quiet. The answer lives somewhere between a similarity score and a model no one on the team can read. It works — until the day it doesn't, and then no one can say why.

We took a different position early at Specicon: a decision you can't explain shouldn't ship. Not as a slogan — as an API contract. Every match that leaves our engines carries a short, human-readable reason, and it's returned in the same response as the score. This post is about why that one design choice changes everything downstream.

The cost of a silent decision

A silent recommendation is expensive in three quiet ways. Support can't defend it, so they apologize for it. Merchandising can't tune it, so they override it. And the customer can't trust it, so they ignore it. None of these show up in an offline metric, but all of them show up in the numbers that matter.

When a match arrives with a reason attached — warm · evening · luxury — each of those failure modes flips. The agent reads the reason aloud. The merchandiser tunes the dimension. The customer nods, because the suggestion finally sounds like it was made for them.

A reason is not a tooltip

The tempting shortcut is to generate an explanation after the ranking — a second model that guesses at why the first one chose. That's a tooltip: plausible, decorative, and occasionally wrong in ways that erode the trust it was meant to build.

Our reason is the opposite. It's assembled from the exact dimensions that produced the score — warmth, intent, value — so it can never disagree with the decision it describes. If the reason and the ranking ever drifted apart, that would be a bug, not a rounding error.

If you can't say why in five words, you don't understand the decision well enough to serve it.

What ships in the response

Here's the shape of it. One call, one decision, and the reason travels beside the score — ready to render on any surface without a second request.

{
  "matches": [
    {
      "sku": "AF-2210",
      "score": 0.93,
      "reason": "warm · evening · luxury"
    }
  ],
  "latency_ms": 18
}

Notice what's not there: no second endpoint, no explanation job, no batch. The reason costs nothing extra because it was never separate.

Reading the same words everywhere

Because the reason is a plain string in the response, the same five words appear on every surface that touches the decision:

• The storefront shows it under the product, so the shopper sees the logic.
• The email carries it into the subject line, so the open is earned.
• The support console surfaces it to the agent, so the answer is consistent.
• The dashboard aggregates it, so merchandising can tune the dimension that's driving lift.

One identity, one decision, one reason — read the same way by everyone. That consistency is what customers actually notice, even when they can't name it.

The discipline it forces

Shipping the reason with the match is a constraint, and constraints are clarifying. It means we can't hide behind a score we can't articulate. It means every new engine has to answer the same question before it goes live: can you say why, in words a buyer would accept?

That's the bar. It's also why we measure everything against a 50/50 holdout (pilot) — a reason you can read is only worth something if the decision behind it actually moves the numbers. Explainability and evidence are the same discipline, pointed at different audiences.