@damiangilgonzalez/harness 1.3.7

package/skills/market-research/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: market-research
+description: "Use when a MARKET as a whole needs a defensible picture — TAM/SAM/SOM sized top-down AND bottom-up until the two converge, cut into reachable segments with one named beachhead, demand proven real, and a dated source behind every figure. NOT profiling named rivals and their moves (that is `competitor-watch`), NOT building a 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 it: a list of accounts with contacts is a sales list → `../lead-gen/SKILL.md`; a rival's tiers, gaps and recent launches is a 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 |
+| --- | --- |
+| **Size it** | Never ship a number without a second, independent method |
+| **Segment it** | Cut by the *job buyers hire you for*, then prove the slice is reachable AND distinct |
+| **Read demand** | Secondary to form the hypothesis, primary to decide it |
+
+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.
+
+## 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 |
+
+### 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, the SAM-then-SOM derivation logic, and the full memo template with its sources/provenance schema 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 buy, and a market with no beachhead is one you can't enter |
+| 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 — you just confirm your own bias |
+
+## 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 above that keep "market sizing" honest: the numeric `SOM ≤ SAM ≤ TAM` nesting, **both** methods plus a stated convergence/divergence note (one method alone fails), and a citation **and** date on every load-bearing figure.
+
+```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 exits `0` on a clean or empty target — a missing memo is a skip, never a false failure.
+
+## 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`.

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 for a whole market — Job 1, the central case for this skill.
+  - 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-language ask 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-language ask 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.

package/skills/market-research/scripts/verify.sh

@@ -0,0 +1,215 @@
+#!/usr/bin/env bash
+#
+# verify.sh — provenance + triangulation gate for the `market-research` skill.
+#
+# WHAT IT DOES (read-only; never edits a file)
+#   Static checks over a produced market memo (Markdown). It validates that the
+#   memo is CROSS-CHECKED AND SOURCED — never whether the market is attractive.
+#   For each memo found:
+#     1. TAM / SAM / SOM all present with a parseable numeric value, AND the
+#        nesting SOM <= SAM <= TAM holds. (Units like $, €, K/M/B/k/m/b/bn are
+#        normalized so 1.4M < 9.5M < 15.8M compares correctly.)
+#     2. Triangulation: evidence of BOTH a top-down and a bottom-up figure, PLUS
+#        a stated convergence/divergence note. A lone method fails.
+#     3. Provenance: a sources section exists, and every figure line in it carries
+#        a citation/URL AND a date (YYYY-MM-DD or a year 19xx/20xx). An undated
+#        load-bearing number fails.
+#
+#   A missing/empty target is a SKIP, never a failure. Floating math uses awk
+#   (POSIX), so no bc needed.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh                      # scan ./ for *memo*/*market*.md
+#   ./verify.sh --path memo.md       # check one memo
+#   ./verify.sh --path research/     # scan a directory of memos
+#   ./verify.sh --strict             # treat warnings as failures (CI gate)
+#
+# EXIT CODES
+#   0  clean, empty target, or warnings only without --strict
+#   1  a real failure (broken nesting, missing method, undated source)
+#   2  bad usage
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; skip_count=0; warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+
+usage() { sed -n '2,33p' "$0" | sed 's/^# \{0,1\}//'; }
+
+SCAN_PATH="."
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path)   SCAN_PATH="${2:?--path needs a value}"; shift 2 ;;
+    --strict) STRICT=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) printf '%sUnknown argument: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+  esac
+done
+
+summary() { printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"; }
+
+if [ ! -e "$SCAN_PATH" ]; then
+  skip "path not found: $SCAN_PATH — nothing to check"
+  skip_count=1; summary; exit 0
+fi
+
+have() { command -v "$1" >/dev/null 2>&1; }
+if ! have awk; then
+  skip "awk not found — cannot parse memo; install awk"
+  skip_count=1; summary; exit 0
+fi
+
+# Collect candidate memo files: prefer named memos/market files, else any .md.
+FILES=""
+if [ -f "$SCAN_PATH" ]; then
+  FILES="$SCAN_PATH"
+else
+  FILES="$(find "$SCAN_PATH" -type f -name '*.md' \( -iname '*memo*' -o -iname '*market*' -o -iname '*sizing*' \) 2>/dev/null || true)"
+  if [ -z "$FILES" ]; then
+    FILES="$(find "$SCAN_PATH" -type f -name '*.md' 2>/dev/null || true)"
+  fi
+fi
+
+if [ -z "$FILES" ]; then
+  skip "no market memo found under $SCAN_PATH — nothing to check (clean)"
+  skip_count=1; summary; exit 0
+fi
+
+# check_one <file>: one awk pass emits "LEVEL message" lines; the shell tallies.
+check_one() {
+  f="$1"
+  [ -s "$f" ] || { printf '%s[skip]%s empty file: %s\n' "$YELLOW" "$NC" "$f"; return; }
+  printf '%s—— %s%s\n' "$YELLOW" "$f" "$NC"
+
+  awk '
+    # NOTE: stock macOS BSD awk has no IGNORECASE and no \b — we lowercase with
+    # tolower() and use explicit (^|non-letter) boundaries instead.
+    # parse_num(s): pull first number with optional $/€ and K/M/B/bn suffix -> value, or "" if none.
+    function parse_num(s,   t,mult,num) {
+      t=s
+      # find a numeric token possibly with thousands separators and a magnitude suffix
+      if (match(t, /[0-9][0-9.,]*[ ]*(bn|[kmbKMB])?/)) {
+        num=substr(t, RSTART, RLENGTH)
+        mult=1
+        if (num ~ /bn/)      { mult=1000000000; sub(/bn/,"",num) }
+        else if (num ~ /[bB]$/) { mult=1000000000; sub(/[bB]$/,"",num) }
+        else if (num ~ /[mM]$/) { mult=1000000;    sub(/[mM]$/,"",num) }
+        else if (num ~ /[kK]$/) { mult=1000;       sub(/[kK]$/,"",num) }
+        gsub(/[ ,]/,"",num)
+        if (num ~ /^[0-9.]+$/ && num != "" && num != ".") return num*mult
+      }
+      return ""
+    }
+    {
+      line=$0
+      lc=tolower($0)
+
+      # --- sizing: capture first numeric value on a line that names the metric ---
+      if (tam=="" && lc ~ /(^|[^a-z])tam([^a-z]|$)/) { v=parse_num($0); if(v!="") tam=v }
+      if (sam=="" && lc ~ /(^|[^a-z])sam([^a-z]|$)/) { v=parse_num($0); if(v!="") sam=v }
+      if (som=="" && lc ~ /(^|[^a-z])som([^a-z]|$)/) { v=parse_num($0); if(v!="") som=v }
+
+      # --- method evidence ---
+      if (lc ~ /top[ -]?down/)  topdown=1
+      if (lc ~ /bottom[ -]?up/) bottomup=1
+      if (lc ~ /converg|diverg|within [0-9]|[0-9] *x|triangulat/) converge=1
+
+      # --- sources section detection ---
+      if (lc ~ /^#+.*source|^#+.*provenance|^\| *figure|^sources/) insrc=1
+      else if (lc ~ /^#+ /) insrc=0   # a new heading ends the sources block
+
+      # within sources, a row that carries a number should also carry a date
+      if (insrc) {
+        srcseen=1
+        if ($0 ~ /[0-9]/ && ($0 ~ /http/ || $0 ~ /\|/)) {
+          # does this line carry a date? YYYY-MM-DD or a 4-digit year
+          if ($0 ~ /(19|20)[0-9][0-9]-[0-1][0-9]-[0-3][0-9]/ || $0 ~ /(19|20)[0-9][0-9]/) {
+            datedrows++
+          } else {
+            undated++
+            if (undated <= 3) print "DETAIL undated source line: " substr($0,1,80)
+          }
+        }
+      }
+    }
+    END {
+      # 1. TAM/SAM/SOM present + nesting
+      miss=""
+      if (tam=="") miss=miss" TAM"
+      if (sam=="") miss=miss" SAM"
+      if (som=="") miss=miss" SOM"
+      if (miss!="") print "FAIL missing sizing value(s):"miss
+      else {
+        print "OK TAM/SAM/SOM all present (" tam " / " sam " / " som ")"
+        if (som <= sam+0.0001 && sam <= tam+0.0001) print "OK nesting SOM<=SAM<=TAM holds"
+        else print "FAIL nesting broken: need SOM(" som ")<=SAM(" sam ")<=TAM(" tam ")"
+      }
+
+      # 2. triangulation
+      if (topdown && bottomup) {
+        print "OK both top-down and bottom-up figures present"
+        if (converge) print "OK convergence/divergence note present"
+        else print "FAIL no convergence/divergence note for the two methods"
+      } else {
+        m=""
+        if (!topdown)  m=m" top-down"
+        if (!bottomup) m=m" bottom-up"
+        print "FAIL triangulation incomplete — missing method(s):"m
+      }
+
+      # 3. provenance
+      if (!srcseen) print "FAIL no sources/provenance section found"
+      else if (undated>0) print "FAIL "undated" source line(s) carry a figure with no date"
+      else if (datedrows>0) print "OK "datedrows" dated source line(s); none undated"
+      else print "WARN sources section present but no figure+date rows detected"
+    }
+  ' "$f" 2>/dev/null
+}
+
+printf 'Checking market memos under: %s\n\n' "$SCAN_PATH"
+printf '%s\n' "$FILES" | while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  check_one "$f"
+done > "/tmp/mr_verify.$$" 2>&1 || true
+
+# Render with colored tags.
+while IFS= read -r line; do
+  case "$line" in
+    FAIL*)   printf '%s[fail]%s %s\n' "$RED"    "$NC" "${line#FAIL }" ;;
+    WARN*)   printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "${line#WARN }" ;;
+    OK*)     printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "${line#OK }" ;;
+    DETAIL*) printf '        %s\n' "${line#DETAIL }" ;;
+    *)       printf '%s\n' "$line" ;;
+  esac
+done < "/tmp/mr_verify.$$"
+
+tally() { { grep -c "$1" "/tmp/mr_verify.$$" 2>/dev/null || true; } | tr -dc '0-9'; }
+fail_count=$(tally '^FAIL'); fail_count=${fail_count:-0}
+warn_count=$(tally '^WARN'); warn_count=${warn_count:-0}
+ok_count=$(tally '^OK');     ok_count=${ok_count:-0}
+skip_count=$(tally '\[skip\]'); skip_count=${skip_count:-0}
+rm -f "/tmp/mr_verify.$$" 2>/dev/null || true
+
+summary
+
+cat <<'EOF'
+
+Note: this gate proves the memo is CROSS-CHECKED AND SOURCED (TAM/SAM/SOM nesting,
+both methods + a convergence note, dated sources). It does NOT judge whether the
+market is attractive — that is the capability eval's job. Re-run with --strict to
+gate CI on a clean pass.
+EOF
+
+if [ "$fail_count" -gt 0 ]; then exit 1; fi
+if [ "$STRICT" -eq 1 ] && [ "$warn_count" -gt 0 ]; then exit 1; fi
+exit 0