Vertical discovery brief — template

Copy this file to documentation/portal/verticals/<slug>/discovery.md and fill it in. Nothing about a vertical gets designed or built until its brief reaches "session complete".

This template exists because we tried the other way first

On 2026-08-09 ten industries were specified in one design prompt. The result was ten cards with an identical section order, because one spec can only describe one shape. The owner's correction, taken 2026-08-10, is one industry at a time: research it, define the merchant Store, define the public Setu Card, validate the whole loop, then move on. This template is that decision made repeatable.

Proportionality, so the twentieth vertical stays cheap: the first industry in an archetype gets a full brief. Each sibling in the same archetype gets a short delta brief that records only what differs, and links here for the rest. A festival stall and a boutique are both goods; the second one should take an hour, not a week.

0 · Front matter

Field	Value
Industry key	<slug> — stable TEXT, never an integer (ADR-0020)
Archetype	goods · time · expertise — exactly one
Primitive composition	e.g. ['catalogue','party','ledger'] — from the closed set of 11
User categories served	1 solo owner · 2 enterprise · 3 consumer (name them; a feature note that omits this is incomplete)
Release	which release, and why now
Status	🔴 not started · 🟡 session booked · 🟡 session complete · 🟢 mapped and approved
Evidence	who was actually spoken to, and when. ⚠ "Inferred from market research" is not discovery

⚠ The Status row is the machine-readable source of truth for the G-D gate (QRS-475). A release scope item declares "vertical": "<slug>"; check:release then requires this brief to exist at status scoped and to read approved at scope_frozen. Replace the menu above with one status — a cell listing every option would read as approved, which is why verticals/_template/ is excluded from the gate's loader and why a test pins that behaviour.

1 · The business, in their words

Answer from a real conversation, not from reasoning about the industry.

1. Who is the merchant? Solo, family-run, staffed? Who actually holds the phone?
2. How do they get customers today? Footfall, referral, WhatsApp status, an aggregator, a marketplace? ⚠ A business fed by an aggregator or by footfall will not do promotional work, which is the test that excluded restaurants and clinics from R1.
3. Vendor pain points — ranked, in their vocabulary. What costs them time, money or sleep?
4. Customer pain points — what does their customer struggle to find out or do?
5. Existing workflows and tools — WhatsApp, a paper ledger, Tally, a notebook, Excel, a competitor app. Name them. What we replace must be better than the notebook, not better than nothing.
6. What information do they already share with customers, and how? This is the highest-signal question in the brief: whatever they are already re-typing every day is what the card should render once.
7. Industry-specific interactions — the verbs that are not order/book/enquire.
8. Edge cases they raised themselves — seasonality, festival peaks, a second shop, a partner, a bad-debt customer.

2 · Content types — ⚠ ADDED 2026-08-10, and it drives the design directly

Not "do they have photos". What KIND of content carries this industry's value, and what shape does it need?

Content type	Needed?	Shape / notes
Photographs		aspect ratio, how many, whose (theirs or stock)
Video		walkthrough · demo · transformation · showcase. Length, and how many
Before / after		is the change the product? (salon, fitness, renovation)
Documents		certificates, brochures, price lists, hallmark certs
A published number that changes		a daily rate, a live price. ⚠ This is a ADR-0027 case — say which of D2/D4/D5
A schedule		classes, slots, opening hours, delivery windows
Structured specs		which fields are filtered or priced upon (typed columns) vs merely displayed (attributes)
Long-form text		FAQ, method, credentials

⚠ Then answer the ADR-0019 D6 question explicitly, because it is the one that costs code: does any of this need a new block type, or is it a config variant of an existing block? A new type needs a written case that it serves ≥2 industries.

3 · Acquisition and conversion — ⚠ ADDED 2026-08-10

1. ⚠ COLD DISCOVERY, and ask it first — ADDED 2026-08-10 (QRS-496): a customer who has never heard of this merchant, how do they find one like them TODAY? Search, footfall, a market they walk, a directory, a referral, an aggregator, a WhatsApp group? Everything else in this section is a warm mechanic — a link travelling to someone who already had a reason to look — and warm mechanics say nothing about whether a marketplace or an SEO surface is worth anything for this industry. The Festival Stall brief answered all four warm questions well and left this one unasked, which left the consumer Marketplace resting on an unverified premise (QRS-490). If the honest answer is "they walk the market", say so — that is a finding, not a failure, and it correctly moves the vertical's value to the card rather than to discovery.
2. Why would this merchant share their card? If there is no honest answer, the growth loop does not run here.
3. What makes their customer forward it? A price list, a rate, an offer, a photo album, a booking link?
4. Where does the card replace something they do manually today? (A WhatsApp album, a status post, a phone call answered fifty times.)
5. Is there a natural referral path — peer to peer, supplier to retailer, teacher to student?
6. What is the acquisition CTA placement for this industry, given that the visitor is a customer, not a prospective merchant? Default: the post-action confirmation screen and the share sheet, never the hero.

4 · Monetization — ⚠ ADDED 2026-08-10

1. What would this merchant pay for, and roughly what? Ask; do not model it.
2. Which capability is the paywall? Name the feature_code, not a tier word.
3. Is there transaction revenue? Payments through Razorpay Route earn commission; an order that leaves through WhatsApp or a direct UPI transfer earns nothing and is invisible to the read model.
4. Is there a second buyer? An enterprise above them (a builder, a brand, a distributor) who would pay for many seats.
5. ⚠ Store-compliance check: any upsell implied here must convert on web or email, never in-app (Apple 3.1.3(d), ADR-0002).

5 · Governance and verification — ⚠ ADDED 2026-08-10

Per ADR-0026, verification gates capabilities, never signup. The default is that nothing is required.

1. Is any capability here legally gated? (A jeweller's savings scheme, an agent's authority to market, a trainer's certification, a direct seller's income claims.)
2. What evidence would be accepted, per industries.verification_requirements?
3. Is there a claim the merchant could make on a public card that we would be the publisher of? Earnings claims, health claims, guaranteed returns, hallmark claims. This is the question that finds the real risk.
4. Does anything here need a legal read before it ships? Name it, and do not design around the answer.

6 · Divergence seams — required at G0, not G3 (QRS-297)

Any capability touching camera, push, storage, share, clipboard, deep links or offline names its implementation or approved fallback per surface (Android native · iOS native · Web PWA) before work starts. There is no exception path.

7 · Proactive-value answer

Per CLAUDE.md's gate, answered before implementing:

• What action does this prompt the merchant to take today?
• What makes it timely?
• Where does the intelligence come from — the analytics read model, archetype config, or a pure @qrsetu/domain derivation? A nudge hardcoded for one vertical is a defect against ADR-0009.

8 · Part 2 — capability mapping (fill in AFTER the session)

Every workflow from Part 1 maps to exactly one row.

Workflow (their words)	Existing capability	New capability needed	Generalises to ≥2 other industries?

The rule that keeps the platform O(primitives) rather than O(industries): anything generalising to one industry only is either genuinely bespoke — which needs written sign-off — or it is mis-modelled. Most apparently-novel workflows collapse into an existing primitive; in the real-estate session six of eight did.

⚠ A new PRIMITIVE requires a written case that it serves ≥3 industries (ADR-0020). A new block type requires ≥2 (ADR-0019 D6). Neither bar is negotiable in a discovery brief; if the case cannot be made, the answer is a config variant or a composition of what exists.

9 · Sign-off

Session held	date, with whom
Capability mapping complete	✅ / ❌
New primitives proposed	none, or the ≥3-industry case
New block types proposed	none, or the ≥2-industry case
Open decisions for the owner
Tracker rows raised	QRS-###