rsc-universal 0.1.1

package/skills/logistics-ops/evals/cases.yaml

@@ -0,0 +1,48 @@
+skill: logistics-ops
+
+should_trigger:
+  - prompt: "Order #1043 is packed and going to a customer two zones away who paid for 2-day — which carrier and service do I use, and cut me the label?"
+    why: SHIP leg — rate-shop against the delivery promise and buy the label, the core outbound ask.
+  - prompt: "The tracker just flipped to 'delivery exception — address issue.' What do I do and what do I tell the customer?"
+    why: EXCEPT leg, tiered protocol. Non-obvious — no word "shipping" or "logistics" appears, but it's the exception-response core.
+  - prompt: "Customers keep opening 'where is my order' tickets — how do I get ahead of that?"
+    why: TRACK leg — proactive tracking notification / WISMO deflection, reads as a support problem but the fix is event-driven tracking here.
+  - prompt: "Gestiona la devolución de este pedido: el cliente dice que la talla no le sirve y quiere cambiarla."
+    why: Spanish trigger — REVERSE leg, changed-mind/size return defaulting to instant exchange over cash refund.
+  - prompt: "A package arrived smashed — how long do I have to file a claim with FedEx and what do I need?"
+    why: Claims — the carrier claim-window + evidence-at-detection ask.
+  - prompt: "Quin transportista surt més barat per a aquest enviament de 5 kg a Madrid en 48 h?"
+    why: Catalan trigger — SHIP leg rate-shop against a delivery promise including DIM/landed cost.
+
+should_not_trigger:
+  - prompt: "How many units of this SKU should I reorder and what's my safety stock?"
+    route_to: inventory
+    why: Stock-level / reorder-point decision, not moving an existing parcel.
+  - prompt: "I need to find a new supplier for these shipping boxes and negotiate payment terms."
+    route_to: procurement
+    why: Inbound vendor sourcing and terms, not the outbound or reverse parcel.
+  - prompt: "Write the empathetic reply to the angry customer whose order is late."
+    route_to: customer-support
+    why: The on-voice apology and reply SLA; this skill supplies the tracker facts, support writes the tone.
+  - prompt: "Record the $80 refund as a credit note in our accounts."
+    route_to: bookkeeping
+    why: Posting the AP/credit-note entry; this skill only decides refund-vs-exchange, not the books.
+  - prompt: "Build the webhook endpoint that receives EasyPost tracker events and retries on failure."
+    route_to: webhooks
+    why: Hosting/plumbing the listener and retries; this skill decides which events fire which action, not how to host them.
+
+capability:
+  - scenario: >
+      An order that shipped 2-day arrived a full day late AND the tracker shows a
+      "delivery exception — damaged." The customer is asking for a cash refund.
+      Ask the skill for the full operational response: how to classify and respond,
+      what to do about the carrier, what to tell the customer, and how to handle the
+      refund.
+    must_include:
+      - classifies the exception as damage and triggers same-business-day proactive outreach (not a 48-h or 24-h tier)
+      - names the FedEx/UPS/USPS claim window and says to file before it closes, capturing evidence (photos, declared value, weight, tracking) NOW at detection
+      - flags that two clocks run — the ~60-day damage claim and the 15-day guaranteed-service refund on the late delivery — and files the 15-day one first
+      - gives a proactive, tracker-fact-based customer message instead of waiting for a WISMO ticket, and hands the reply tone/SLA to customer-support
+      - on the refund, offers instant exchange or store credit before cash to retain revenue, and does not charge a restocking fee because the cause is damage (seller-side)
+      - routes the refund accounting to bookkeeping and any restock decision to inventory rather than doing them here
+      - does NOT invent a delivery ETA the carrier has not provided

package/skills/logistics-ops/references/carriers-and-claims.md

@@ -0,0 +1,105 @@
+# Carriers, exception codes, and claim windows
+
+Lookup material offloaded from the spine: the per-carrier exception-code map, the
+full claim matrix with required evidence, and runnable EasyPost snippets. All facts
+accessed 2026-06-02 (Sifted / ShipperHQ / Goshippo / LateShipment / FedEx / USPS /
+ShippingEasy / Cahoot / EasyPost docs).
+
+## Normalize the exception code to one of four buckets
+
+Carriers emit different codes for the same physical event. Map to a bucket, then run
+the protocol from the SKILL's EXCEPT table.
+
+| Bucket | Physical event | Typical FedEx wording | Typical UPS wording | Typical USPS wording |
+| ------ | -------------- | --------------------- | ------------------- | -------------------- |
+| Address / access | Bad, incomplete, or inaccessible address | "Incorrect address", "Customer not available or business closed" | "Address Correction", "The receiver was not available" | "No Access to Delivery Location", "Insufficient Address" |
+| Failed attempt | Carrier tried, nobody/access to receive | "Delivery attempted" | "A delivery attempt was made" | "Delivery Attempted - No Access" |
+| Weather / operational | Weather, network, mechanical delay | "Local delivery restriction — weather", "Operational delay" | "Adverse weather conditions", "Emergency situations or natural disasters" | "Emergency weather delay", "Processing exception" |
+| Damage / loss | Item damaged, lost, or contents missing | "Shipment damaged", "Package handling — damaged" | "This package was damaged in transit" | "Damaged in Transit", "Loss/rifling" |
+
+Rule: never route on the raw string. Two carriers will name "we couldn't deliver"
+four different ways — bucket first, then apply the severity clock.
+
+## Full claim-window matrix
+
+Windows vary by **service class** within a carrier; treat these as the governing
+defaults and confirm the exact class before relying on a date. Filing late = the
+claim is denied and the money is gone.
+
+| Carrier | Claim type | Window | Required evidence |
+| ------- | ---------- | ------ | ----------------- |
+| USPS | Damage / missing contents | File no later than **60 days** from mailing date | Proof of value (receipt/invoice), evidence of insurance, photos of damage + packaging |
+| USPS | Lost | After the service-specific waiting period, within the filing window for the class | Proof of value, proof of insurance, tracking |
+| UPS | Damage | Notice within **60 days** of delivery date | Photos of item + packaging, declared value, tracking, label |
+| UPS | Lost / undelivered | Within **60 days** of the scheduled delivery date | Proof of value, tracking, label |
+| UPS | Guaranteed-service refund | Within **15 days** of the invoice date | The carrier invoice showing the service + late scan |
+| FedEx | Damage / missing contents (US) | Within **60 days** of the ship date | Photos of item + packaging, value, weight/dims, tracking, label |
+| FedEx | Damage / missing (international) | Within **21 days** of delivery | As above |
+| FedEx | Lost / undelivered | Up to **9 months** from ship date | Proof of value, tracking, label |
+| FedEx | Guaranteed-service refund | Within **15 days** of the invoice date | Invoice showing the committed service + the missed commitment |
+
+Two clocks run at once on a guaranteed shipment that arrives damaged and late: the
+**damage claim** (≈60 days) and the **service-refund claim** (≈15 days from invoice).
+The 15-day refund clock is the one operators miss — file it first.
+
+## EasyPost snippets
+
+### Rate-shop + one-call buy
+
+```python
+import easypost
+client = easypost.EasyPostClient(api_key)
+
+shipment = client.shipment.create(
+    to_address={"name": "...", "street1": "...", "city": "...",
+                "state": "...", "zip": "...", "country": "US"},
+    from_address=from_address,
+    parcel={"length": 9.0, "width": 6.0, "height": 3.0, "weight": 12.0},
+)
+
+# Restrict to services that meet the promised delivery date upstream, then:
+rate = shipment.lowest_rate(carriers=["USPS", "UPS", "FedEx"])
+bought = client.shipment.buy(shipment.id, rate=rate)
+
+label_url = bought.postage_label.label_url
+tracking_code = bought.tracking_code
+tracker = bought.tracker          # status starts at pre_transit
+```
+
+### Tracker webhook handler shape (event-driven, not polled)
+
+EasyPost POSTs a `tracker.updated` event each time the parcel's status changes.
+Decide the action per status; let `webhooks` own the actual endpoint/retries.
+
+```python
+def handle_easypost_event(event):
+    if event["description"] != "tracker.updated":
+        return
+    tracker = event["result"]
+    status = tracker["status"]            # in_transit, out_for_delivery, exception, delivered
+    if status == "exception":
+        bucket = normalize_exception(tracker["status_detail"])  # → one of the four buckets
+        route_to_protocol(bucket, tracker)        # severity clock from the EXCEPT table
+        notify_customer_proactively(tracker)      # facts only; tone → customer-support
+    elif status in ("out_for_delivery", "delivered"):
+        notify_customer_proactively(tracker)
+```
+
+### Reverse label — same create call, `is_return: true`
+
+```python
+return_shipment = client.shipment.create(
+    to_address=from_address,    # your warehouse
+    from_address=customer_addr, # the customer (to/from swap)
+    parcel=parcel,
+    is_return=True,
+)
+return_label = client.shipment.buy(
+    return_shipment.id, rate=return_shipment.lowest_rate()
+)
+# Email return_label.postage_label.label_url to the customer.
+```
+
+Carrier coverage for rate-shop breadth: EasyPost ~100+ carriers, Shippo ~85+,
+ShipStation ~200+. Choosing/hosting the integration is
+`api-connector-builder` / `webhooks`; this skill decides which calls fire when.

package/skills/market-research/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: market-research
+description: "Use when you need a defensible picture of a MARKET as a whole — sizing it with TAM/SAM/SOM, cutting it into reachable segments, and proving demand is real and moving — with a dated source behind every number. Triggers: 'how big is the market for X', 'size this market', 'what's our TAM', 'is there real demand for this', 'who are the segments', 'where's the beachhead', 'sanity-check this TAM before the raise', 'top-down or bottom-up', '¿qué tamaño tiene el mercado de X', 'calcula el TAM', 'hay demanda real para esto', 'quina mida té aquest mercat'. NOT profiling specific named rivals and their moves (that is competitor-watch), NOT building a named list of accounts to sell to (that is lead-gen)."
+tags: [market-research, tam-sam-som, market-sizing, segmentation, demand-signals, jtbd, opportunity]
+recommends: [competitor-watch, lead-gen, pitch-deck, financial-model, pricing, forecasting, content-engine]
+origin: risco
+---
+
+# Market research — the size/segment/signal engine
+
+You are the market-understanding engine. Someone hands you a fuzzy "is there a market for X?" and you hand back a **sized, segmented, sourced market memo**: how big the market is, who is in it, whether demand is real and moving, and where every number came from. Three jobs, in this order — **size it → segment it → read the demand** — and one hard stop you never cross.
+
+The test of this work is not the number. It is **whether someone else can audit the number.** A `$50B TAM` you assert is a guess wearing a suit. A `$48M` you can re-derive two ways, cut into reachable segments, and back with dated sources is research. Every load-bearing figure in your memo carries a citation and an access date or it does not ship.
+
+## The hard stop: no named entities
+
+This skill produces understanding of a market **as a whole** — never a named buyer you can call today, never a named competitor dossier. The moment the ask turns into "who specifically," stop and route:
+
+- "Give me 200 fintech accounts with the VP Eng contact" → that is a sales list → `../lead-gen/SKILL.md`.
+- "Profile Competitor X — their tiers, gaps, recent launches" → that is a rival dossier → `../competitor-watch/SKILL.md`.
+
+Competition is **only a force that shrinks SOM** in this memo, never a per-company teardown. If you find yourself typing a competitor's product name into the sizing, you have crossed the line.
+
+## The three jobs
+
+| Job | One governing rule | Failure if skipped |
+| --- | --- | --- |
+| **Size it** | Never ship a number without a second, independent method | A lone figure is unfalsifiable; readers discount it |
+| **Segment it** | Cut by the *job buyers hire you for*, then prove the slice is reachable AND distinct | A market with no beachhead is a market you can't enter |
+| **Read demand** | Secondary to form the hypothesis, primary to decide it | You confirm your own bias with stale reports |
+
+Do them in order — sizing tells you what to segment, segments tell you where to read demand. The artifact at the end ties all three together with a sources table. That memo is what `scripts/verify.sh` lints.
+
+## Job 1 — Size it (triangulate or it's a guess)
+
+Two instruments, two different errors. Run **both** and force them to agree.
+
+| Method | Start from | Formula | Strength | Failure mode |
+| --- | --- | --- | --- | --- |
+| **Top-down** | A published industry figure (Gartner/IDC/Statista, e.g. "$70B CRM market") | `industry size × your segment share %` | Fast, anchors to a named source | Inherits and amplifies the report's error; easy to hand-wave the share % |
+| **Bottom-up** | Your customers + price | `ACV × number of ICP-fitting accounts` | Grounded in your own pricing; survives investor scrutiny | Slow; needs a real ICP and a real account count |
+| **Triangulation** | BOTH of the above | Run both, force them to agree | The actual credibility signal | Skipping it — a lone number is a guess |
+
+### The triangulation gate
+
+Triangulation is the credibility test, **not the number itself.** 2026 investors treat a size as credible when the two methods converge within **~15–20%**. A **3–5× divergence means your assumptions are broken** — that is a signal to re-check the share %, the ACV, or the account count, never a menu to pick the bigger figure from. Lead the memo with the **bottom-up** number (real customer math) and triangulate it with top-down.
+
+```text
+Bad   "TAM = $50B."                          # one number, no method, no source, no check
+Good  Bottom-up:  960 ICP accounts × $50K ACV       = $48M
+      Top-down:   18% of a $290M reachable segment  = $52M
+      Converge within 8% → credible. Lead with $48M.
+```
+
+### TAM / SAM / SOM are nested, not interchangeable
+
+- **TAM** — total demand if you owned 100% of the market.
+- **SAM** — the slice your business model + geography can actually serve.
+- **SOM** — the slice you can realistically capture near-term, given competition and sales capacity.
+
+The funnel `SAM ≈ 20% of TAM`, `SOM ≈ 10% of SAM` is an **illustrative example to defend, not a constant to assume.** Derive SAM from your real reach (model, geography, language) and SOM from the competitive pressure and your sales capacity — then state why. Worked top-down and bottom-up calculations, the convergence math, and the full memo template live in `references/sizing-playbook.md`.
+
+## Job 2 — Segment it (reachable AND distinct, with a named beachhead)
+
+Four classic axes — **geographic, demographic, behavioral, firmographic** (~81% of B2B marketers use firmographics). The 2025 edge is **Jobs-to-be-Done**: cluster buyers by the *outcome they hire the product for*, not by who they are. The why is blunt — people buy outcomes, not demographics. Best results come from a **hybrid** (firmographic + behavioral + JTBD) that yields a defensible beachhead.
+
+Name the **beachhead** — the one segment you win first. Then run every segment through this test before it earns a row in the memo:
+
+- **Distinct need?** Does this slice hire the product for a different job than the others?
+- **Reachable channel?** Is there a concrete way to get in front of them (not "the internet")?
+- **Big enough to matter?** Does it move the SOM, or is it a rounding error?
+- **Different enough to message separately?** If the pitch is identical to another segment, it is not a real segment.
+
+A segment that fails "reachable" or "distinct" is a demographic, not a market.
+
+## Job 3 — Read the demand (signal vs vanity)
+
+Secondary and primary research answer different questions. **Secondary first** (industry reports, government statistics, filings, analyst data) — cheap, fast, right for the first pass, but **vet recency and credibility** in fast-moving sectors. Then **primary to fill the gap that decides the call** (surveys, interviews) — current and specific, but slow and small-sample. Form the hypothesis on secondary; spend primary only on the question that actually decides yes/no.
+
+**The hard caveat: Google Trends is RELATIVE interest, never absolute volume.** Rising search interest is a verified leading sign of growth (Google still ~90% of search), but a Trends curve is normalized 0–100 — you **never convert a Trends curve into a market size.** Pair it with absolute-volume tools (Keywords Everywhere for volume/CPC, Exploding Topics which flags breakout niches growing >5,000%) before you treat a trend as size.
+
+```text
+Bad   "Search interest doubled on Google Trends → the market is $2B."   # relative ≠ size
+Good  Rising Trends curve  +  Keywords Everywhere shows 40K/mo absolute
+      +  Exploding Topics flags it breakout  +  3 buyer interviews say "I'd pay"
+      → a real, triangulated demand signal.
+```
+
+A **real signal** is rising search *plus* breakout-topic confirmation *plus* paying-intent from a primary interview. **Vanity** is one viral spike, a single curve, or a report with no date. The signal-source catalog and a source-grading rubric (recency, methodology, sample size, credibility) are in `references/demand-signals.md`.
+
+## The market memo (the artifact)
+
+Every market-research output has the same fixed shape so it can be audited and handed off:
+
+1. **Hypothesis** — the one-line market question being tested.
+2. **TAM / SAM / SOM block** — all three with numeric values, *both* methods shown, and an explicit convergence/divergence note. SOM ≤ SAM ≤ TAM must hold.
+3. **Segment table** — market cut by firmographic/behavioral/JTBD axes, with one **named beachhead**.
+4. **Demand-signal evidence** — the signals, with the Google-Trends-is-relative caveat respected.
+5. **Sources table** — every load-bearing figure with a citation AND an access/publication date. No undated number survives this row.
+
+This is exactly what `scripts/verify.sh` checks. Keep it Markdown so the linter can parse it.
+
+## Anti-patterns
+
+| Bad | Good | Why |
+| --- | --- | --- |
+| Ship one TAM number, no second method | Run top-down AND bottom-up, state the convergence | A lone figure is unfalsifiable; readers discount it |
+| "$50B market" with no source or year | Cite the report + access date for every figure | Undated/unsourced = a guess; markets move fast |
+| Top-down and bottom-up are 4× apart, pick the bigger | Re-check inputs until they converge ≤~20% | 3–5× divergence means broken assumptions, not a choice |
+| Convert a Google Trends curve into a market size | Pair with absolute-volume tools before sizing | Trends is RELATIVE interest, never absolute volume |
+| Segment by demographics alone | Add JTBD/behavioral; name a reachable beachhead | Demographics miss *why* people actually buy |
+| Treat SAM/SOM as fixed 20%/10% of TAM | Derive SAM from reach, SOM from competition + capacity | Those ratios are illustrative, not constants |
+| Name specific competitor products in the memo | Treat competition as a SOM-shrinking force | A dossier is scope creep — hand to competitor-watch |
+| List named target accounts as "the market" | Hand the segment to lead-gen to build the list | That is a sales list, not market understanding |
+| All secondary data, no primary check on the decisive question | Use interviews/survey to fill the gap that decides | Stale or misaligned reports mislead the call |
+
+## Verify
+
+The memo is a checkable artifact, so `scripts/verify.sh` lints a produced memo file (read-only — it never edits) for the three things that keep "market sizing" honest:
+
+```bash
+./scripts/verify.sh                     # scan ./ for *memo*/*market*.md
+./scripts/verify.sh --path memo.md      # check one memo
+./scripts/verify.sh --path research/    # scan a directory of memos
+./scripts/verify.sh --strict            # treat warnings as failures (CI gate)
+```
+
+It asserts: (a) **TAM, SAM, SOM** all present with parseable numeric values and the nesting `SOM ≤ SAM ≤ TAM` holds; (b) evidence of **both** a top-down and a bottom-up figure plus a stated **convergence/divergence** note — fails if only one method is present; (c) a **sources** section where each load-bearing figure carries a citation/URL AND a date. It exits `0` on a clean or empty target — a missing memo is a skip, never a false failure. The memo schema it enforces is documented in `references/sizing-playbook.md`.
+
+## Hand-offs
+
+The memo is the start of a chain. When it is done, route:
+
+- Present the sizing as the opportunity slide → `../pitch-deck/SKILL.md`.
+- Model revenue off the SOM → `../financial-model/SKILL.md`.
+- Turn a named segment into an actionable account list → `../lead-gen/SKILL.md`.
+- Profile the rivals that shrink the SOM → `../competitor-watch/SKILL.md`.
+- Set the ACV the bottom-up math depends on → `../pricing/SKILL.md`.
+- Project the demand series forward from history → `../forecasting/SKILL.md`.
+- Act on the keyword/topic demand signals → `../content-engine/SKILL.md`.
+
+## references/
+
+- `references/sizing-playbook.md` — worked top-down and bottom-up calculations side by side, the triangulation convergence math (≤~15–20% credible, 3–5× broken), the SAM-then-SOM derivation logic, and the full market-memo template including the mandatory sources/provenance table schema.
+- `references/demand-signals.md` — the signal-source catalog (Google Trends + its relative-volume caveat, Exploding Topics, Statista, government/industry data, primary survey/interview design) and a source-grading rubric for vetting secondary data by recency and credibility.

package/skills/market-research/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — market-research
+
+`cases.yaml` holds three groups for this skill's router and capability. Run them against whatever eval harness the repo provides, or check by hand: feed each `should_trigger` prompt to the router and confirm it selects `market-research` (including the non-obvious ones — cross-checking an existing TAM, the top-down-vs-bottom-up method choice, and the Spanish/Catalan sizing asks); feed each `should_not_trigger` prompt and confirm it routes to the named sibling (`competitor-watch` for a named-rival dossier, `lead-gen` for a named account list, `pitch-deck` for the slide, `financial-model` for the revenue model, `forecasting` for a single-series forecast) and not here — these encode the boundaries that bleed. The `capability` case is graded against its `must_include` rubric on an actual generated memo for the dental-clinic scenario: tick each line (TAM/SAM/SOM with nesting, both methods plus a convergence note, a segment table with one beachhead, a demand signal that respects the Google-Trends-is-relative caveat, a dated sources table, derived rather than assumed SAM/SOM, no competitor dossier, and an explicit hand-off). Pair the capability grade with `scripts/verify.sh` against the generated memo file to confirm the artifact actually holds up — TAM/SAM/SOM nesting, both-methods-plus-convergence, and dated sources — where the rubric judges research quality and verify.sh judges structural integrity. No automated harness is assumed beyond reading the prompts and checking routing plus the rubric.

package/skills/market-research/evals/cases.yaml

@@ -0,0 +1,48 @@
+skill: market-research
+
+should_trigger:
+  - prompt: "How big is the market for AI legal-research tools in Spain?"
+    why: Core sizing request — "how big is the market for X" is the central trigger.
+  - prompt: "Sanity-check this TAM before our seed raise — does $2B hold up?"
+    why: Non-obvious; cross-checking an existing number IS the triangulation core, not deck design or modeling.
+  - prompt: "Cut our addressable market into segments and tell me which one to attack first."
+    why: Segmentation plus naming the beachhead — Job 2 of this skill.
+  - prompt: "Is there actually demand for a B2B carbon-accounting product, or are we imagining it?"
+    why: Demand-signal validation of a market hypothesis — Job 3, secondary-then-primary.
+  - prompt: "Should we size this top-down from the industry report or bottom-up from our customers?"
+    why: Non-obvious; the top-down-vs-bottom-up choice and triangulation gate are this skill's method, not a generic data pull.
+  - prompt: "¿Qué tamaño tiene el mercado de software de reservas para restaurantes y cuál es el TAM/SAM/SOM?"
+    why: Spanish trigger for the full sizing job — TAM/SAM/SOM explicitly requested.
+  - prompt: "Quina mida té el mercat d'apps de reserves i hi ha demanda real?"
+    why: Catalan trigger combining market size and demand validation — both core jobs.
+
+should_not_trigger:
+  - prompt: "Profile Competitor X — their pricing tiers, feature gaps, and recent product launches."
+    route_to: competitor-watch
+    why: A named-rival dossier with moves over time, not market-as-a-whole understanding.
+  - prompt: "Build me a list of 200 SaaS companies in fintech with the VP Eng contact for each."
+    route_to: lead-gen
+    why: An actionable list of named accounts/contacts to sell to, not a sized market.
+  - prompt: "Turn this market sizing into the opportunity slide for our deck."
+    route_to: pitch-deck
+    why: Presenting an already-produced sizing as a slide, not producing the sizing.
+  - prompt: "Build the 3-year revenue model off our SOM."
+    route_to: financial-model
+    why: Modeling forward revenue/costs off the SOM, not sizing the market.
+  - prompt: "Forecast next year's demand from our last 24 months of sales data."
+    route_to: forecasting
+    why: A single-series statistical forecast from existing history, not market sizing or signal validation.
+
+capability:
+  - scenario: >
+      Product idea: a B2B scheduling tool for dental clinics in Spain. Assumed ACV is
+      €1,200/clinic/year. You have access to web research. Produce a market memo.
+    must_include:
+      - TAM, SAM and SOM all present with numeric values, and SOM <= SAM <= TAM nesting holds.
+      - BOTH a top-down figure (industry/segment source) AND a bottom-up figure (ACV × ICP account count), with an explicit convergence/divergence note.
+      - A segment table cutting the market by firmographic/behavioral/JTBD axes with exactly one named beachhead.
+      - At least one demand signal cited, with the Google-Trends-is-relative caveat respected (no Trends curve treated as absolute size).
+      - A sources table where every load-bearing figure has a citation/URL AND an access or publication date.
+      - SAM and SOM derived from stated reasons (reach, language/geography, competition, capacity) — not assumed as flat 20%/10% of TAM.
+      - No named competitor products treated as dossiers; competition appears only as a SOM-shrinking force.
+      - An explicit hand-off note (pitch-deck for the slide, financial-model for revenue, lead-gen for the list, competitor-watch for rivals).

package/skills/market-research/references/demand-signals.md

@@ -0,0 +1,63 @@
+# Demand signals — source catalog and grading rubric
+
+How to tell a real demand signal from vanity interest, and how to grade the sources
+you cite. Secondary forms the hypothesis; primary decides the call.
+
+## Signal-source catalog
+
+| Source | What it gives | Watch out for |
+| --- | --- | --- |
+| **Google Trends** | RELATIVE search interest (0–100, normalized) over time + by region | Never absolute volume; never convert a curve into a market size; small terms are noisy |
+| **Keywords Everywhere** | Absolute monthly search volume + CPC per keyword | Paid; volumes are estimates — use for order-of-magnitude, not precision |
+| **Exploding Topics** | Breakout niches; flags topics growing >5,000% | Early signal, small base — a breakout topic is a hypothesis, not a proven market |
+| **Statista / analyst reports** | Published market sizes, growth rates, segment splits | Check publication date and methodology; fast sectors go stale in months |
+| **Government / industry registries** | Account counts, establishment counts, official statistics | Authoritative but lagging; definitions may not match your ICP |
+| **Company filings (10-K, annual reports)** | Real revenue, segment disclosures from public players | Public-co skew; not the whole market |
+| **Primary surveys** | Current, quantifiable intent from your target buyers | Slow; sampling bias; leading questions ruin it |
+| **Primary interviews / focus groups** | The *why* behind the buy, paying-intent, objections | Tiny n; great for hypotheses, weak for sizing |
+
+## Secondary first, primary to decide
+
+- **Secondary** (reports, gov stats, filings, analyst data) is cheap, fast, and right
+  for the **first pass** — but vet recency and credibility in fast-moving sectors.
+  Use it to form the hypothesis and to size top-down.
+- **Primary** (surveys, interviews) is current, specific, and controllable but slow and
+  small-sample. Spend it on **the one question that decides yes/no** — usually
+  "will the ICP actually pay the ACV?" — not on facts a report already answers.
+
+## Real signal vs vanity interest
+
+A signal is **real** when independent indicators stack:
+
+```text
+Real    rising Google Trends curve
+        + absolute volume confirms a meaningful base (Keywords Everywhere)
+        + Exploding Topics flags it breakout
+        + a primary interview shows paying intent at your price
+        → triangulated demand
+
+Vanity  one viral spike on a single Trends curve
+        a report with no date
+        "everyone needs this" with no search or interview evidence
+        → discard or downgrade
+```
+
+The same discipline as sizing: one indicator is a guess, stacked independent indicators
+are a finding.
+
+## Source-grading rubric
+
+Grade every secondary source before you cite it. A figure from a low-grade source needs
+a primary cross-check before it becomes load-bearing.
+
+| Dimension | High grade | Low grade (cross-check before relying) |
+| --- | --- | --- |
+| **Recency** | Published/updated within the sector's half-life (months for fast tech) | Older than the last major market shift |
+| **Methodology** | States how the number was derived (sample, model, definitions) | Black-box "industry estimates" with no method |
+| **Sample / coverage** | Large, representative, matches your geography + ICP | Tiny, skewed, or a different market than yours |
+| **Credibility** | Named analyst/gov/registry with a track record | Vendor marketing page sizing its own category |
+| **Independence** | Not selling the thing being sized | The report's author profits from a big number |
+
+Record the grade implicitly by what you do: a high-grade source can stand alone in the
+sources table; a low-grade one must be paired with a second source or a primary check,
+and both rows carry their dates.

package/skills/market-research/references/sizing-playbook.md

@@ -0,0 +1,121 @@
+# Sizing playbook — top-down, bottom-up, triangulation, and the memo template
+
+Worked numbers for one example market so you can copy the *shape*, not the figures.
+Replace every number with your own, sourced and dated.
+
+## The example market
+
+Hypothesis: *"Is there a venture-scale market for a B2B scheduling tool for dental
+clinics in Spain?"* Assumed ACV (annual contract value): **€1,200/clinic/year**.
+
+## Bottom-up (lead with this one)
+
+Bottom-up = `ACV × number of ICP-fitting accounts`. It is grounded in your own
+pricing and a reachable account count, so it survives scrutiny.
+
+```text
+ICP            independent dental clinics in Spain, 1–4 chairs, already digital-booking-curious
+Account count  ~22,000 dental clinics in Spain (gov/industry registry)   [source + date]
+                × 60% that fit the ICP (size + digital readiness)         = 13,200 accounts
+ACV            €1,200/clinic/year                                          [your pricing]
+Bottom-up TAM  13,200 × €1,200                                            = €15.8M
+```
+
+Note what each line needs: the **account count** needs a sourced, dated registry
+figure; the **ICP filter %** needs a stated rationale; the **ACV** comes from
+`../pricing/SKILL.md`. If any of the three is a vibe, the whole number is a vibe.
+
+## Top-down (the cross-check)
+
+Top-down = `published industry size × your segment share %`. Fast, but it inherits
+the report's error and tempts you to hand-wave the share.
+
+```text
+Industry figure   Spain dental-practice-management software market ~€90M   [Statista/analyst, date]
+Your segment      scheduling/booking module ≈ 18% of that spend            = €16.2M
+Top-down TAM      €16.2M
+```
+
+## The triangulation gate
+
+```text
+Bottom-up   €15.8M
+Top-down    €16.2M
+Divergence  |16.2 − 15.8| / 15.8 = 2.5%   →  well within ~15–20%  →  CREDIBLE
+Lead with   €15.8M (bottom-up), cross-checked by €16.2M (top-down).
+```
+
+Convergence reading:
+
+| Divergence | Verdict | Action |
+| --- | --- | --- |
+| ≤ ~15–20% | Credible | Ship it; lead with bottom-up |
+| ~20–100% | Shaky | Re-check the weakest input (usually the segment share % or the ICP filter) |
+| 3–5× apart | Broken | Assumptions are wrong — do NOT pick the bigger; find which input lies |
+
+The divergence is the *finding*. A clean convergence is your credibility; a 4× gap is
+a bug report telling you which assumption to fix.
+
+## SAM and SOM (derive, never assume 20%/10%)
+
+TAM/SAM/SOM are nested. Derive each from a real constraint and state it:
+
+```text
+TAM   €15.8M    all Spanish dental clinics that could buy scheduling software
+SAM   €9.5M     Castilian/Catalan-language product, mainland + islands, cloud-only
+                = the slice your model + geography + language can actually serve (~60% of TAM)
+SOM   €1.4M     3-year realistic capture: 2 incumbents hold most accounts, you have
+                a 4-rep capacity → ~15% of SAM near-term
+```
+
+Write the *reason* beside each ratio. "SAM is 60% of TAM because the product ships in
+Castilian/Catalan and excludes clinics on legacy on-prem suites" is defensible.
+"SAM = 20% of TAM" with no reason is the anti-pattern.
+
+## Market-memo template
+
+The fixed artifact. Keep it Markdown so `scripts/verify.sh` can parse it.
+
+```markdown
+# Market memo — <market name>
+
+## Hypothesis
+<the one-line market question being tested>
+
+## Sizing (TAM / SAM / SOM)
+- TAM: €15.8M  — bottom-up: 13,200 ICP accounts × €1,200 ACV
+- TAM (top-down cross-check): €16.2M — 18% of a €90M segment
+- Convergence: 2.5% → credible. Lead with bottom-up €15.8M.
+- SAM: €9.5M  — Castilian/Catalan, cloud-only, ~60% of TAM (reason stated)
+- SOM: €1.4M  — ~15% of SAM, 3-yr, given 2 incumbents + 4-rep capacity
+- Nesting check: SOM €1.4M ≤ SAM €9.5M ≤ TAM €15.8M ✓
+
+## Segments
+| Segment | Axis | The job they hire for | Reachable via | Beachhead? |
+|---|---|---|---|---|
+| Solo urban clinics | firmographic + JTBD | "fill last-minute cancellations" | dental-supplier channel | ★ beachhead |
+| Small chains (2–4) | firmographic | "centralize multi-site booking" | direct sales | no (later) |
+
+## Demand signals
+- Google Trends "cita dentista online" rising (RELATIVE interest — not size)
+- Keywords Everywhere: ~40K/mo absolute searches [source + date]
+- Exploding Topics: flags "online dental booking" breakout [source + date]
+- 5 clinic-owner interviews: 4 of 5 would pay at €1,200 [primary, date]
+
+## Sources
+| Figure | Source / URL | Date accessed |
+|---|---|---|
+| 22,000 clinics in Spain | <registry url> | 2026-06-02 |
+| €90M PMS software market | <Statista url> | 2026-06-02 |
+| 40K/mo search volume | <Keywords Everywhere> | 2026-06-02 |
+
+## Hand-off
+Sizing → pitch-deck; SOM → financial-model; beachhead → lead-gen;
+incumbents → competitor-watch; ACV → pricing.
+```
+
+## The provenance rule
+
+Every figure in the sizing and signals sections must appear as a row in the **Sources**
+table with both a citation/URL **and** a date (access or publication). A number without
+a sources-table row is undated and does not ship — that is the rule `verify.sh` enforces.