# Query generation

Five shopper questions per run. What those five are depends on what the brand sells.

## Tailored questions (`tailored-v2`)

Built from the [brand profile](brand-profile.md). Comparison questions come first, then
archetype-specific questions fill the remainder, then duplicates are removed. The result
is at most 5 questions and at least 2.

**Comparison questions** use the first two competitors from the profile:
`compare {brand} vs {competitor}`. With no known competitors, this becomes
`compare {brand} vs other {offering} providers`.

**Archetype-specific questions**, in priority order:

+++ ecommerce
- `best {offering} brands`
- `best {offering} for {buyer}` (with ` in {geography}` when known)
- `best {offering} under $50` — **only** when `price_band` is `budget`
- `buy me the best {offering}`
- `what {offering} do you recommend and why?`
- one job query
+++ saas
- `best {offering} tools`
- `best {offering} for {buyer}`
- two job queries
- `what {offering} do you recommend and why?`
+++ service
- two job queries
- `best {offering} for {buyer}`
- `best {offering} firms` (with ` in {geography}` when known)
- `what {offering} do you recommend and why?`
+++ unknown
- `best {offering}`
- `best {offering} for {buyer}`
- two job queries
- `what {offering} do you recommend and why?`
+++

!!!info Price questions are conditional
`best {offering} under $50` is emitted only for a `budget` price band. Asking it of a
firm that quotes five-figure engagements produces a question no real shopper asks, and
then penalizes the firm 15 points for not ranking in the answer.
!!!

## Job queries

A job phrase renders as `who can help me {phrase}`. Before rendering, first-person
prefixes are stripped, and the job is **dropped entirely** if it is under 3 characters,
over 14 words, or still begins with a subject word. A malformed question is discarded
rather than asked, because a nonsense question produces a real penalty.

## Generic questions (`generic-v1`)

The fallback set, used only when profile extraction fails:

1. `best {category} brands`
2. `best {category} under $50`
3. `compare {brand} vs {competitor}` — once per competitor, or against "other {category} brands"
4. `buy me the best {category} product`
5. `what {category} do you recommend and why?`

These use the caller-supplied `category`, which is why they are a fallback and not a
default: the caller's idea of its own category is frequently not the shopper's.

## Comparability

Every run records its `query_set_version`. Two runs are only comparable when both the
version **and** the actual question text match — see
[Measurement reliability](reliability.md#what-is-done-about-it).