market-evaluator

name	market-evaluator
description	Rank the candidates that survived conformance evaluation and produce a purchase recommendation — a top three in order, each with product, price and where to actually buy it, followed by category picks such as best budget, best overall and best for features. Use once conformance records exist and the question has moved from "which of these qualify" to "which should I buy", when someone asks for a recommendation or a shortlist ranked, or when a matrix has narrowed the field and a decision is now needed. Ranks only candidates that clear every disqualifying requirement, and states its weighting rather than hiding it in a score.
allowed-tools	Read, Write, Edit, Glob, Grep, WebSearch, WebFetch, Agent, Bash(python3 *), Bash(ls *), Bash(cat *), Bash(mkdir *)

Market evaluator

The step after the conformance matrix. The matrix answers who qualifies and deliberately refuses to rank — no scores, no weighted totals, no ordering, because a weighted total buries the trade-offs the matrix exists to expose.

This skill is where ranking is allowed to happen, precisely because it is separate and explicit about what it weighted.

Inputs: spec.yaml (or spec-<variant>.yaml), evaluation/conformance/*.json, and price/availability data if price-scan has run. Output: evaluation/recommendation.md.

Run evaluation-matrix first. Without conformance records this skill has nothing to rank and must not improvise one from listings.

The gate: who is even rankable

Before ranking anything, partition the candidates. This is not a formality — it is the step that stops a cheap non-compliant product topping the list.

• Rankable — every must is pass and every must-not is clear.
• Blocked — a disqualifying requirement is unknown. Not a low rank; not rankable at all. Listed separately with the specific evidence that would unblock it. An unknown on a must is missing information, and burying it as a slightly-lower position presents ignorance as judgement.
• Excluded — a confirmed fail on a disqualifying requirement. One line each, naming the requirement. They are in the matrix; do not re-argue them.

nice requirements never gate. They are tie-breakers, and they are most of what distinguishes the rankable set from one another.

If nothing is rankable, say so plainly and stop. The output is then the blocked list and what would unblock it. Do not relax the spec to produce a recommendation — if the bar is wrong, that is a spec revision the user makes knowingly, via update-spec or spec-as-code.

Output shape

Write evaluation/recommendation.md in this order, always.

1. Top three, in order — always first

Even where the field is larger. Three ranked picks, best first, each carrying:

Field	Requirement
Product	Manufacturer, model, and the exact part number for the user's region. A part number that cannot be bought where they are is not a recommendation.
Price	Landed cost where known — unit price, shipping, duty and tax — in the user's currency, with the date and source. Say "unit price only, landed cost not established" rather than presenting a bare figure as if it were the total.
Sourcing	Where to actually buy it: named vendors, stock state, lead time. At least one concrete route per pick, or an explicit "no source found in region", which is itself a finding.
Why this position	One or two sentences. What it clears that the one below it does not, or what it trades.
What it costs you	The trade-off accepted. Every pick has one; a pick presented with no downside has not been examined.

If fewer than three qualify, give what there is and say why the list is short. Do not pad the third slot with a candidate that is blocked or excluded.

Sourcing is the half most often skipped, and it is the half that makes the recommendation actionable. If price and availability have not been established, run price-scan, or say explicitly that the ranking is on specification alone and the prices are indicative.

2. Category picks

After the top three, and only where the category is genuinely distinct — say so when one candidate wins several, rather than manufacturing a different name for each slot:

• Best overall — the balanced pick. Usually but not always #1; where it differs, that is interesting and should be explained.
• Best budget — cheapest that still clears every must. Never a non-compliant product, however cheap.
• Best for features — most nice requirements met, cost secondary.
• Best value — the knee in the curve: where the next increment of money stops buying a proportionate increment of capability.
• Add others when the spec justifies them — best for availability when lead time is the binding constraint, best for support where that was a requirement.

One line of justification each, referencing requirement ids.

3. What decided it

State the weighting as a sentence, not a score: "ranked on setpoint accuracy first (REQ-002), then landed cost, then warranty; transient response was not separating them."

If the spec gives priorities, use them and say so. If it does not, say which weighting you applied and that the user can reorder it. Weighting is a judgement and must be visible enough to argue with — a number in a column is not.

4. Blocked and excluded

Both lists, as above. The blocked list is the actionable one: each entry names the requirement, why it is unresolved, and the specific evidence that would settle it.

5. Provenance

Spec identity (id@variant rN), how many conformance records were read, and the date. If any record was evaluated against an older revision, name it — its verdicts may predate the current bar.

With variants

One recommendation per variant, not one merged ranking. Budget's winner and premium's winner are answers to different questions, and averaging them answers neither.

Write evaluation/recommendation-<variant>.md per variant, then a short comparison at the end of each: what the extra money actually buys, and whether the premium bar turned out to be reachable at all. That comparison is usually the most useful output of running variants, and it is the input to converging them.

Discipline

Never rank on evidence the matrix rejected. If a must needed a datasheet and only a retail listing exists, the cell is unknown and the candidate is blocked. Do not let a plausible review promote it.

Price does not override conformance. A cheaper non-compliant product is not a budget option; it is excluded. The budget pick is the cheapest compliant one.

Say when it is close. Where the top two are separated by one nice requirement or a small price delta, say so. A confidently-ordered list that is actually a coin toss is worse than a stated tie, because the user cannot tell which they are being handed.

Do not re-research. This step reads conformance records; it does not re-litigate cells. If a cell looks wrong, fix it in the record and regenerate the matrix — a recommendation that quietly contradicts the matrix it cites makes both untrustworthy.

Carry marketplace caveats through. A delivery date that was conditional, a price excluding a coupon, a stock figure from a signed-in session — each changes the comparison and each disappears if only the number is recorded. See marketplace-handoff.