Buyer Lens

buyer-lens

Evaluate a product or page the way its buyers would, using the semantic similarity rating (SSR) method from Maier et al., arXiv:2510.08338. The paper's core findings drive every rule here: LLM panels reproduce human purchase-intent rankings only when respondents are conditioned on concrete buyer attributes and react in free text first — asking for a 1–5 rating directly collapses variance into uniform 4s and the results stop matching human panels.

Work through the steps in order. Do not skip step 4 (the maps) or step 6 (the script) — they exist because models grade only what a page says and miscount distribution arithmetic.

Step 0 — Intake

If the request already names a website URL or describes the product, do not re-ask. Otherwise ask one question: what website or product should be reviewed (a URL is preferred — a live page shows what buyers actually see, including what's missing). Defaults, stated not asked: 2–4 buyer segments, 5 respondents per segment.

Step 1 — Capture the concept

Fetch the page with browser tools (navigate + screenshot + accessibility snapshot) when available; plain HTTP fetch renders many SPAs as an empty shell, and you would review a page the buyer never sees. If the page will not render at all (auth wall, 404, blocked), say so and run from the user's description instead — never grade an empty shell as though it were the concept. Record verbatim: headline claims, capabilities, integrations, pains addressed, CTAs, and pricing. If no pricing is shown, record that as a concept attribute — buyers read absent pricing as "expensive" and it depresses stated intent.

Step 2 — Identify the buyer segments

Infer 2–4 segments from the page's own targeting (who it's sold to, whose vocabulary it borrows), including any intermediary segment (the accountant, agency, or reseller who recommends onward) — pages usually forget these and that gap is itself a finding. State the segments and proceed; ask only if the target buyer is genuinely undecidable from the material.

Step 3 — Build the personas

Read references/persona-schema.md before writing any persona. Personas must be conditioned on the attributes that predict purchase behavior — workflows by cadence, tool stack with spend, budget authority, buying process — not demographic vibes; the paper found budget/income conditioning replicates human response patterns best, age next, gender/region unreliably. When the domain is unfamiliar, web-search to ground tool names, workflows, and typical spend — never invent vendors or prices from memory.

Step 4 — Map coverage and competition (before any elicitation)

Build two maps from the personas, because silence is data a respondent won't volunteer:

• Workflow-coverage gap map — classify every persona workflow as Covered /

Named-only / Missing against the concept. Rank the misses by frequency × money at stake × incumbent weakness.

• Incumbent frame — per segment: the status quo (often a spreadsheet or

doing nothing, not software), overlapping incumbent tools, and web-verified named alternatives a shopping buyer would compare.

Step 5 — Run the panel

Read references/ssr-protocol.md before eliciting the first respondent. The non-negotiables, with the reasons they exist:

• Free text only, never a rating — direct numeric elicitation produces

unrealistically narrow, over-confident distributions (the paper's baseline failure).

• One respondent at a time, each blind to the others — a single batched pass

makes respondent 4 contrarian because 1–3 were positive, which is theater, not variance. For real isolation, write an elicitation spec (personas + concept; shape in the script's --help) and run python3 scripts/panel_runner.py spec.json -o reactions.json — it elicits every respondent in its own fresh headless context. Preview with --plan first; if the claude CLI is unavailable it says so — then elicit in-conversation, one respondent per message.

• Vary respondents on budget pressure, age/tenure, size, and incumbent

satisfaction — attribute variance is where real distribution spread comes from.

• Reactions must name the status quo they'd displace; real intent is

displacement intent.

Step 6 — Score with the script

Write the panel to JSON — shape documented in the script's --help, worked example at examples/sample-panel.json. Save it somewhere durable (the project directory or wherever the user keeps research), named -.panel.json — not a temp directory, because the re-test workflow below needs this exact file to survive until the concept is revised. Then from this skill's folder run:

python3 scripts/panel_math.py .json

It validates every distribution (sums to 1.0, no over-confident spikes), computes expected values and segment aggregates, and prints the headline table. Distribution arithmetic is deterministic work; done by hand it gets quietly miscounted. Use --compare .json when re-testing a revised concept against the same panel.

Step 7 — Write the report

Read references/report-template.md and follow its shape. The report must end with prioritized, concrete suggestions tied to respondent evidence (what would move the 3s to 4s), and must carry the caveats verbatim: the reliable outputs are relative rankings between segments and concepts, objection themes, and budget-pressure effects; absolute purchase-intent levels are not conversion forecasts.

Comparing variants

To test revised pages, price points, or competing concepts: same respondent variants, same order, one saved panel file per variant, then

python3 scripts/panel_math.py v1.panel.json v2.panel.json v3.panel.json

which prints a segment × variant ranking matrix (two files also works; --compare remains for a single before/after diff). Relative ranking between variants is what the method demonstrably recovers (≈90% of human test–retest reliability in the paper); never present a single run's absolute mean as a forecast. The script warns if the variants' respondent sets differ — ranking is only protocol-valid on identical panels.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ujjwalks
• Source: ujjwalks/buyer-lens
• License: MIT

Install and usage instructions live in the source repository linked above.