@diottodev/runic 1.0.0 → 1.1.0

package/research-ops/skills/clinical-research/scripts/sample_size_estimator.py

@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""sample_size_estimator.py - Closed-form sample-size / power estimates for common trial designs.
+
+Stdlib-only. Deterministic. NO LLM calls. This is an ESTIMATE, not a protocol:
+every output prints a banner instructing the user to confirm with a biostatistician.
+
+Supported designs (normal-approximation closed forms):
+  - means        two-sample comparison of means (Cohen's d effect size)
+  - proportions  two-sample comparison of proportions (arcsine-free normal approx)
+  - survival     two-arm log-rank, Schoenfeld events approximation
+
+z-values come from a small built-in lookup table (no scipy dependency).
+
+Usage:
+    python3 sample_size_estimator.py --sample
+    python3 sample_size_estimator.py --design means --effect 0.5 --alpha 0.05 --power 0.8
+    python3 sample_size_estimator.py --design proportions --p1 0.30 --p2 0.45 --dropout 0.15
+    python3 sample_size_estimator.py --design survival --hr 0.65 --power 0.9 --output json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+try:
+    import config_loader as _cfg
+except ImportError:  # pragma: no cover - skill always ships config_loader
+    _cfg = None
+
+BANNER = "ESTIMATE ONLY — confirm with a biostatistician before finalizing the protocol."
+
+# Two-sided z for alpha, and one-sided z for power (1 - beta). Lookup avoids scipy.
+Z_ALPHA_TWO_SIDED = {0.10: 1.6449, 0.05: 1.9600, 0.025: 2.2414, 0.01: 2.5758}
+Z_POWER = {0.80: 0.8416, 0.85: 1.0364, 0.90: 1.2816, 0.95: 1.6449, 0.975: 1.9600}
+
+
+def _z_alpha(alpha: float) -> float:
+    if alpha not in Z_ALPHA_TWO_SIDED:
+        raise ValueError(f"alpha must be one of {sorted(Z_ALPHA_TWO_SIDED)} (two-sided).")
+    return Z_ALPHA_TWO_SIDED[alpha]
+
+
+def _z_power(power: float) -> float:
+    if power not in Z_POWER:
+        raise ValueError(f"power must be one of {sorted(Z_POWER)}.")
+    return Z_POWER[power]
+
+
+def _inflate(n: float, dropout: float) -> int:
+    if not 0.0 <= dropout < 1.0:
+        raise ValueError("dropout must be in [0, 1).")
+    return math.ceil(n / (1.0 - dropout))
+
+
+def estimate_means(effect: float, alpha: float, power: float, allocation: float, dropout: float) -> dict:
+    """Two-sample means. effect = Cohen's d (standardized mean difference)."""
+    if effect <= 0:
+        raise ValueError("effect (Cohen's d) must be > 0.")
+    za, zb = _z_alpha(alpha), _z_power(power)
+    # Equal-n per-arm: n = 2 * ((za + zb) / d)^2 ; unequal handled via allocation ratio k.
+    k = allocation
+    base = ((za + zb) / effect) ** 2
+    n1 = (1 + 1.0 / k) * base
+    n2 = (1 + k) * base
+    return {
+        "design": "means",
+        "effect_size_cohens_d": effect,
+        "alpha_two_sided": alpha,
+        "power": power,
+        "allocation_ratio_k": k,
+        "n_group1_raw": math.ceil(n1),
+        "n_group2_raw": math.ceil(n2),
+        "n_group1_with_dropout": _inflate(n1, dropout),
+        "n_group2_with_dropout": _inflate(n2, dropout),
+        "dropout_assumed": dropout,
+        "formula": "n_i = (1 + 1/k or k) * ((z_alpha + z_beta)/d)^2",
+    }
+
+
+def estimate_proportions(p1: float, p2: float, alpha: float, power: float, dropout: float) -> dict:
+    """Two-sample proportions, normal approximation (pooled + unpooled variance term)."""
+    for p in (p1, p2):
+        if not 0.0 < p < 1.0:
+            raise ValueError("p1 and p2 must be in (0, 1).")
+    if p1 == p2:
+        raise ValueError("p1 and p2 must differ.")
+    za, zb = _z_alpha(alpha), _z_power(power)
+    pbar = (p1 + p2) / 2.0
+    delta = abs(p1 - p2)
+    num = (za * math.sqrt(2 * pbar * (1 - pbar)) + zb * math.sqrt(p1 * (1 - p1) + p2 * (1 - p2))) ** 2
+    n_per_arm = num / (delta ** 2)
+    return {
+        "design": "proportions",
+        "p1": p1,
+        "p2": p2,
+        "absolute_difference": round(delta, 4),
+        "alpha_two_sided": alpha,
+        "power": power,
+        "n_per_arm_raw": math.ceil(n_per_arm),
+        "n_per_arm_with_dropout": _inflate(n_per_arm, dropout),
+        "n_total_with_dropout": 2 * _inflate(n_per_arm, dropout),
+        "dropout_assumed": dropout,
+        "formula": "n = [z_a*sqrt(2*pbar*qbar) + z_b*sqrt(p1q1+p2q2)]^2 / (p1-p2)^2",
+    }
+
+
+def estimate_survival(hr: float, alpha: float, power: float, prob_event: float, dropout: float) -> dict:
+    """Two-arm log-rank, Schoenfeld events approximation + n from event probability."""
+    if hr <= 0 or hr == 1.0:
+        raise ValueError("hazard ratio must be > 0 and != 1.")
+    if not 0.0 < prob_event <= 1.0:
+        raise ValueError("prob_event (overall probability of event) must be in (0, 1].")
+    za, zb = _z_alpha(alpha), _z_power(power)
+    log_hr = math.log(hr)
+    # Schoenfeld: total events E = 4*(za+zb)^2 / (log HR)^2  (1:1 allocation)
+    events = 4.0 * ((za + zb) ** 2) / (log_hr ** 2)
+    n_total = events / prob_event
+    return {
+        "design": "survival",
+        "hazard_ratio": hr,
+        "alpha_two_sided": alpha,
+        "power": power,
+        "required_events_raw": math.ceil(events),
+        "overall_event_probability": prob_event,
+        "n_total_raw": math.ceil(n_total),
+        "n_total_with_dropout": _inflate(n_total, dropout),
+        "dropout_assumed": dropout,
+        "formula": "E = 4*(z_a+z_b)^2 / (ln HR)^2 ; n = E / P(event)",
+    }
+
+
+def _render_human(result: dict) -> str:
+    lines = [f"!! {BANNER}", "", f"Design: {result['design']}", ""]
+    for k, v in result.items():
+        if k == "design":
+            continue
+        lines.append(f"  {k:28s} : {v}")
+    lines += [
+        "",
+        "Assumptions block (state these in the protocol statistical section):",
+        f"  - alpha (two-sided): {result.get('alpha_two_sided')}",
+        f"  - power (1 - beta):  {result.get('power')}",
+        f"  - dropout inflation: {result.get('dropout_assumed')}",
+        "  - The effect/difference/HR must trace to a published or anchor-based source.",
+        "",
+        f"Named owner required: {result.get('_biostatistician') or 'a biostatistician (run onboard.py to name one)'} "
+        "must sign the final sample-size justification.",
+    ]
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description="Closed-form clinical sample-size / power estimates (ESTIMATE ONLY).")
+    p.add_argument("--design", choices=["means", "proportions", "survival"], default="means")
+    p.add_argument("--alpha", type=float, default=None, help="two-sided alpha (0.10/0.05/0.025/0.01)")
+    p.add_argument("--power", type=float, default=None, help="target power (0.80/0.85/0.90/0.95/0.975)")
+    p.add_argument("--dropout", type=float, default=None, help="anticipated dropout fraction [0,1)")
+    # means
+    p.add_argument("--effect", type=float, default=0.5, help="Cohen's d (means design)")
+    p.add_argument("--allocation", type=float, default=1.0, help="allocation ratio k = n2/n1 (means)")
+    # proportions
+    p.add_argument("--p1", type=float, default=0.30, help="control proportion")
+    p.add_argument("--p2", type=float, default=0.45, help="treatment proportion")
+    # survival
+    p.add_argument("--hr", type=float, default=0.65, help="hazard ratio (survival)")
+    p.add_argument("--prob-event", type=float, default=0.60, help="overall probability of event (survival)")
+    p.add_argument("--output", choices=["human", "json"], default="human")
+    p.add_argument("--sample", action="store_true", help="run the embedded sample (means design)")
+    args = p.parse_args(argv)
+
+    conf = _cfg.load_config() if _cfg else {}
+    alpha = args.alpha if args.alpha is not None else conf.get("default_alpha", 0.05)
+    power = args.power if args.power is not None else conf.get("default_power", 0.80)
+    dropout = args.dropout if args.dropout is not None else conf.get("default_dropout", 0.0)
+    biostat = (conf.get("owners") or {}).get("biostatistician")
+
+    try:
+        if args.sample:
+            result = estimate_means(0.5, alpha, power, 1.0, dropout if dropout else 0.15)
+        elif args.design == "means":
+            result = estimate_means(args.effect, alpha, power, args.allocation, dropout)
+        elif args.design == "proportions":
+            result = estimate_proportions(args.p1, args.p2, alpha, power, dropout)
+        else:
+            result = estimate_survival(args.hr, alpha, power, args.prob_event, dropout)
+    except ValueError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+    result["_biostatistician"] = biostat
+
+    if args.output == "json":
+        result["_banner"] = BANNER
+        print(json.dumps(result, indent=2))
+    else:
+        print(_render_human(result))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/research-ops/skills/market-research/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: market-research
+description: Use when doing upstream market-research methodology — sizing a market as TAM/SAM/SOM computed BOTH top-down and bottoms-up (never a single unsourced number), planning a survey sample size with finite-population correction and per-segment minimums, or scoring candidate market segments against Kotler's measurable/substantial/accessible/differentiable/actionable criteria. Outputs always show the method and the assumptions. For market-research analysts and product-marketing at the sizing/survey/segmentation moment. Distinct from marketing-skill (campaign analytics, attribution, demand-gen) — this is the evidence-building methodology, not live-campaign optimization.
+version: 2.9.0
+author: claude-code-skills
+license: MIT
+tags: [research-ops, market-research, tam-sam-som, market-sizing, survey, sampling, segmentation, competitive-intelligence]
+compatible_tools: [claude-code, codex-cli, cursor, antigravity, opencode, gemini-cli]
+---
+
+# market-research
+
+Upstream market-research methodology: market sizing, survey/sampling design, and segmentation. The discipline here is **method + assumptions**: a TAM is never a single number, a survey is never powered only in aggregate, and a segment is never a demographic slice.
+
+## Purpose
+
+Market-research analysts, product marketers, and strategy teams need rigorous evidence *before* anyone optimizes a campaign or sets a strategy. This skill structures three methodology decisions:
+
+Three deterministic tools:
+
+1. `market_sizer.py` — Computes TAM/SAM/SOM by **both** top-down and bottoms-up methods side-by-side, reports the divergence, and flags failed triangulation. Never returns a single number.
+2. `sample_size_planner.py` — Survey sample size from confidence, margin of error, and expected proportion, with the finite-population correction and **per-segment minimums** (a survey powered overall is not powered per reported segment).
+3. `segmentation_scorer.py` — Scores candidate segments against Kotler's five criteria and enforces a substantiality + accessibility gate; a slice that is too small or unreachable is dropped.
+
+## When to use
+
+Invoke this skill when:
+
+- A board or exec asks "how big is this market?" and you need a defensible, triangulated answer.
+- You are fielding a survey and need a sample size that holds up per segment, not just overall.
+- You have a list of candidate segments and need to know which are real markets vs demographic slices.
+- You are synthesizing competitive intelligence and need a methodological backbone.
+
+**Do NOT use this skill to**: measure a live campaign (attribution, ROAS, CPA → `marketing-skill/campaign-analytics`), build demand-gen / paid-media plans (`marketing-skill/marketing-demand-acquisition`), set positioning / GTM strategy (`marketing-skill/marketing-strategy-pmm`), or set pricing (`commercial/pricing-strategist`).
+
+## Workflow
+
+1. **Write the brief** — Fill `assets/market_research_brief_template.md` (objective, the decision this informs, sizing approach, sampling plan, assumptions register).
+2. **Size the market** — Run `market_sizer.py --input market.json --method both --profile {b2b-saas|consumer|enterprise|marketplace|hardware|services}`. Reconcile the top-down/bottoms-up delta before quoting anything.
+3. **Plan the survey** — Run `sample_size_planner.py --input survey.json`. Fund the per-segment floors, not just the overall n.
+4. **Score the segments** — Run `segmentation_scorer.py --input segments.json --profile <same>`. Drop segments failing the substantiality/accessibility gate.
+5. **Assemble the evidence pack** — Combine into a brief. Every number carries its method + assumptions + confidence.
+
+## Scripts
+
+| Script | Purpose | Profiles |
+|---|---|---|
+| `scripts/market_sizer.py` | TAM/SAM/SOM top-down AND bottoms-up + triangulation flag | b2b-saas, consumer, enterprise, marketplace, hardware, services |
+| `scripts/sample_size_planner.py` | Survey n + FPC + per-segment minima | n/a (parameter-driven) |
+| `scripts/segmentation_scorer.py` | Kotler 5-criteria scoring + gate | b2b-saas, consumer, enterprise, marketplace, hardware, services |
+
+All three: stdlib-only, `--help`, `--sample`, `--output {human,json}`.
+
+## Onboarding & customization
+
+Run the onboarding questionnaire **once before you start** — it captures your defaults so every tool in this skill is pre-configured. Customization is the point: the answers actually change tool behavior.
+
+```bash
+python3 scripts/onboard.py            # interactive (also: --defaults, --set key=value, --reset)
+python3 scripts/onboard.py --show     # see the questions + current effective config
+```
+
+Answers are saved to `~/.config/research-ops/market-research.json` (global) or `./.research-ops/market-research.json` (`--scope project`) and are read automatically by `config_loader.py`. They set the default market **profile**, the default survey **confidence** and **margin of error**, and the default **sizing method**. CLI flags always override saved config; `RESEARCH_OPS_NO_CONFIG=1` ignores it.
+
+**The four questions:** market profile · survey confidence · margin of error · sizing method.
+
+## Optimize with autoresearch (opt-in)
+
+This skill ships an **isolated, opt-in** bridge to `engineering/autoresearch-agent`. Only when you ask to "optimize" / "reconcile the sizing" / "run a loop" does an autoresearch experiment iteratively reconcile your market model so top-down and bottoms-up triangulate. `scripts/ar_evaluator.py` is the ground-truth evaluator; it prints `tam_divergence: <fraction>` (**lower** is better).
+
+```bash
+/ar:setup --domain custom --name tam-triangulation \
+  --target market.json \
+  --eval "python3 ar_evaluator.py --target market.json" \
+  --metric tam_divergence --direction lower
+/ar:loop custom/tam-triangulation
+```
+
+Isolated: no hard dependency — autoresearch runs only on demand, and the loop edits `market.json`, never the evaluator.
+
+## References
+
+- `references/market_sizing_canon.md` — TAM/SAM/SOM frameworks (Bessemer, a16z); top-down vs bottoms-up; Fermi estimation; market-model conventions; common sizing fallacies.
+- `references/survey_methodology.md` — Cochran *Sampling Techniques*; Dillman *Tailored Design Method*; Groves *Survey Methodology*; question-wording bias (Schuman & Presser); AAPOR standards.
+- `references/segmentation_and_ci.md` — Kotler segmentation criteria; needs-based vs firmographic; Porter Five Forces; SCIP ethics; Christensen JTBD; conjoint/MaxDiff primer.
+
+## Assumptions
+
+- The sizer reports both methods but cannot validate your inputs — a top-down "1% of a $40B market" is only as good as the cited source and the serviceable fraction.
+- Sample-size uses the conservative p=0.5 (maximum variance) unless you supply an expected proportion.
+- Segment scores are inputs you provide; the tool enforces the gates and the weighting, it does not gather the underlying evidence.
+- Competitive intelligence must follow the SCIP code of ethics — no misrepresentation, no protected information.
+
+## Anti-patterns
+
+- **A single TAM number with no method.** Always triangulate top-down against bottoms-up.
+- **Spurious precision.** Size to the decision's tolerance; "$3.7142B" implies a confidence you do not have.
+- **Powering only the total.** Each reported segment needs its own sample floor.
+- **Leading or double-barreled survey questions.** Pre-test wording against the bias literature.
+- **Calling a demographic slice a segment.** It must be substantial AND accessible.
+
+## Distinct from
+
+| Neighbor | Scope | Difference |
+|---|---|---|
+| `marketing-skill/campaign-analytics` | Attribution, ROAS, CPA, funnel of a live campaign | That **measures spend deployed**; this is **upstream methodology** |
+| `marketing-skill/marketing-demand-acquisition` | Demand-gen, paid media, channel mix | That **runs acquisition**; this **builds the evidence** |
+| `marketing-skill/marketing-strategy-pmm` | Positioning, GTM, category | That **sets strategy**; this **sizes and segments the market** |
+| `commercial/pricing-strategist` | Pricing model + WTP + packaging | That **sets price**; this **sizes the market** |
+| `product-research` (sibling) | User/product discovery methods | That studies **users**; this studies **the market** |
+
+## Quick examples
+
+```bash
+python3 scripts/market_sizer.py --sample
+python3 scripts/sample_size_planner.py --population 62000 --confidence 0.95 --moe 0.05
+python3 scripts/segmentation_scorer.py --sample --output json
+```
+
+The sample market triangulates a ~$1.47B top-down SAM against the bottoms-up figure and flags the divergence; the segmentation sample drops the "solopreneurs who might want analytics" slice for failing the substantiality and accessibility gates.
+
+## Forcing-question library (Matt Pocock grill discipline)
+
+Walked one at a time by `/cs:grill-research-ops` or the orchestrator. Recommended answer + canon citation per question. Never bundled.
+
+1. **"Is your TAM top-down or bottoms-up — and have you computed it both ways to triangulate?"**
+   Recommended: both; reconcile the delta before quoting a number.
+   Canon: Bessemer / a16z market-sizing; Fermi estimation.
+
+2. **"What decision will this market size actually drive — and at what precision does it matter?"**
+   Recommended: size to the decision's tolerance, not to a spurious-precision number.
+   Canon: market-model conventions (Gartner/Forrester); decision-driven analysis.
+
+3. **"What's your target margin of error and confidence — and does your sample clear it per segment, not just overall?"**
+   Recommended: power each reported segment, not only the total.
+   Canon: Cochran *Sampling Techniques*; AAPOR standards.
+
+4. **"Are your survey questions free of leading and double-barreled wording?"**
+   Recommended: pre-test the wording; cite the bias source.
+   Canon: Schuman & Presser; Dillman *Tailored Design Method*.
+
+5. **"Do your segments pass measurable / substantial / accessible / actionable — or are they just demographic slices?"**
+   Recommended: drop segments that fail substantiality or accessibility.
+   Canon: Kotler segmentation criteria.
+
+Walk depth-first. Lock 1-2 before opening 3-5. After all are answered, invoke `market_sizer.py` → `sample_size_planner.py` → `segmentation_scorer.py`.

package/research-ops/skills/market-research/assets/market_research_brief_template.md

@@ -0,0 +1,36 @@
+# Market Research Brief — Template
+
+> Fill this before running the tools. Every number in the final brief must carry its method,
+> assumptions, and confidence. Size to the decision's tolerance, not to false precision.
+
+## 1. Objective
+- Research question:
+- **The decision this informs** (and who makes it):
+- Precision required (order-of-magnitude / ±20% / ±5%):
+
+## 2. Market sizing
+- Approach: [top-down | bottoms-up | both — recommended both]
+- Top-down inputs: total market value + source citation; serviceable fraction; reachable share.
+- Bottoms-up inputs: total potential customers + source; annual price; serviceable fraction; realistic adoption.
+- Triangulation result (from `market_sizer.py`) + divergence:
+
+## 3. Survey plan (if primary data)
+- Population (N) + sampling frame:
+- Confidence level / overall margin of error / expected proportion:
+- Segments to report + per-segment margin of error:
+- Recommended n (overall + per-segment floors, from `sample_size_planner.py`):
+- Mode (online panel / phone / mixed) + coverage risk:
+
+## 4. Segmentation
+- Candidate segments + scores across measurable / substantial / accessible / differentiable / actionable:
+- Verdicts (from `segmentation_scorer.py`): TARGET / WATCH / DROP
+
+## 5. Competitive intelligence
+- Sources (public, ethically obtained — SCIP code):
+- Five Forces summary:
+
+## 6. Assumptions register
+- (List every assumption behind the sizing, sampling, and segmentation. Each must trace to a source or be flagged as an unverified planning assumption.)
+
+## 7. Confidence statement
+- Overall confidence in the headline numbers (high / moderate / low) and why:

package/research-ops/skills/market-research/references/market_sizing_canon.md

@@ -0,0 +1,36 @@
+# Market Sizing Canon
+
+Reference for TAM/SAM/SOM. Pairs with `market_sizer.py`.
+
+## The three numbers
+
+- **TAM (Total Addressable Market)** — total revenue if you captured 100% of the market for your category.
+- **SAM (Serviceable Addressable Market)** — the portion of TAM you can serve given your geography, segment focus, and product scope.
+- **SOM (Serviceable Obtainable Market)** — the realistic, capacity-constrained share of SAM you can win in the planning window.
+
+## Two methods — always do both
+
+- **Top-down**: start from a published total market value (analyst report, government statistic) and apply serviceable and reachable fractions. Fast, but only as good as the source and inherits its biases. The classic failure is "1% of a huge number" — a TAM that sounds enormous and means nothing.
+- **Bottoms-up**: start from the number of potential customers × the price they would pay, then apply serviceable and adoption fractions. Slower but grounded in units you can defend. The discipline is that bottoms-up forces you to name customer counts and price points.
+
+When the two methods diverge by more than a tolerance, **triangulation has failed** — you do not yet have a defensible number. The tool flags this rather than averaging the two (averaging hides the disagreement).
+
+## Fermi discipline
+
+Good sizing is Fermi estimation: decompose the unknown into knowable factors, estimate each with a stated assumption, and carry the uncertainty through. A market size is a chain of assumptions; surfacing the chain is the deliverable, not the point estimate.
+
+## Common fallacies
+
+- **Double counting** — summing overlapping segments or counting the same revenue at multiple layers of the value chain.
+- **Percent-of-a-big-number** — anchoring on "if we just get 1%" without a bottoms-up cross-check.
+- **Confusing TAM growth with your growth** — a growing TAM does not entitle you to a fixed share.
+- **Spurious precision** — quoting a TAM to four significant figures when the inputs are order-of-magnitude estimates.
+
+## Sources
+
+1. Bessemer Venture Partners, *State of the Cloud* and market-sizing memos (TAM/SAM/SOM discipline).
+2. Andreessen Horowitz (a16z), *The truth about market sizing* and bottoms-up TAM essays.
+3. Gartner / Forrester / IDC market-model methodology notes (forecast construction conventions).
+4. Weinstein, L., & Adam, J., *Guesstimation* (Princeton, 2008) — Fermi estimation.
+5. Blank, S., *The Four Steps to the Epiphany* — market-type and sizing in customer development.
+6. Damodaran, A., *Narrative and Numbers* (Columbia, 2017) — disciplining market-size narratives with numbers.

package/research-ops/skills/market-research/references/segmentation_and_ci.md

@@ -0,0 +1,43 @@
+# Segmentation and Competitive Intelligence
+
+Reference for segmentation scoring and competitive-intelligence synthesis. Pairs with `segmentation_scorer.py`.
+
+## What makes a segment useful (Kotler)
+
+A market segment is only useful if it meets five criteria. The scorer weights and gates them:
+
+1. **Measurable** — you can size and identify it.
+2. **Substantial** — it is large and profitable enough to be worth serving. (Gate: a tiny slice is not a market.)
+3. **Accessible** — you can reach it through channels you can afford. (Gate: an unreachable segment is academic.)
+4. **Differentiable** — it responds differently to your offer than other segments do; otherwise it is not a distinct segment.
+5. **Actionable** — you can design and execute a program for it.
+
+Substantiality and accessibility are **gates** because they are the two that most often fail silently: teams fall in love with a precisely-described segment that is too small or has no viable channel.
+
+## Bases of segmentation
+
+- **Firmographic** (B2B): industry, size, geography — easy to measure, weak at predicting behavior.
+- **Demographic** (B2C): age, income, role — same trade-off.
+- **Needs-based / behavioral**: grouping by the job customers are trying to get done. Stronger predictor of response, harder to measure. Christensen's **Jobs-to-be-Done** reframes segmentation around the progress a customer is trying to make, not who they are.
+
+The strongest segmentations pair a needs-based core with a firmographic/demographic proxy you can actually target.
+
+## Competitive intelligence
+
+CI synthesis is structured, ethical analysis of the competitive landscape:
+
+- **Porter's Five Forces** frames structural attractiveness (rivalry, new entrants, substitutes, supplier power, buyer power).
+- **SCIP (Strategic and Competitive Intelligence Professionals)** publishes a code of ethics: no misrepresentation of identity, no acquisition of protected/confidential information, full compliance with law. CI is built from public and ethically-obtained sources.
+
+## Advanced preference measurement
+
+When you need to quantify trade-offs, **conjoint analysis** and **MaxDiff** (best-worst scaling) estimate the relative importance of attributes and the willingness to trade one for another — far more reliable than directly asking "how important is X?"
+
+## Sources
+
+1. Kotler, P., & Keller, K., *Marketing Management*, 15th ed. — segmentation criteria.
+2. Christensen, Hall, Dillon & Duncan, *Competing Against Luck* (2016) — Jobs-to-be-Done.
+3. Porter, M., *Competitive Strategy* (1980) — Five Forces.
+4. SCIP, *Code of Ethics for CI Professionals*.
+5. Orme, B., *Getting Started with Conjoint Analysis*, 4th ed. (Sawtooth, Research Publishers).
+6. Smith, W., *Product Differentiation and Market Segmentation as Alternative Marketing Strategies* — J Marketing 1956 (the founding segmentation paper).

package/research-ops/skills/market-research/references/survey_methodology.md

@@ -0,0 +1,39 @@
+# Survey Methodology
+
+Reference for survey design and sampling. Pairs with `sample_size_planner.py`.
+
+## Sample size from first principles
+
+For estimating a proportion, the required sample is n₀ = z²·p·(1−p)/e², where z is the critical value for the confidence level, p the expected proportion, and e the margin of error. The maximum-variance choice p = 0.5 is the conservative default. When the sample is a meaningful fraction of a finite population N, apply the **finite-population correction**: n = n₀ / (1 + (n₀−1)/N). The planner does both.
+
+The most common analyst error: powering the **overall** sample but then reporting **per-segment** results that the sample cannot support. If you will report three segments at ±8%, each segment needs ~150 respondents — so the survey must be sized to the segment floors, not the aggregate. The planner computes per-segment minimums explicitly.
+
+## The total survey error framework
+
+Sample size only addresses **sampling error**. Groves' total-survey-error framework names the others, often larger:
+
+- **Coverage error** — the sampling frame omits part of the population (e.g., an email panel misses non-users).
+- **Non-response error** — those who respond differ systematically from those who don't.
+- **Measurement error** — the instrument itself biases answers (question wording, order, scale).
+
+A tight margin of error on a biased frame is precision without accuracy.
+
+## Question design
+
+- **Avoid leading questions** that imply a preferred answer.
+- **Avoid double-barreled questions** that ask two things at once ("Is the product fast and reliable?").
+- **Watch scale and order effects** — response options and question sequence shift answers.
+- **Pre-test** every instrument with a small cognitive-interview pass before fielding.
+
+## Standards
+
+AAPOR (American Association for Public Opinion Research) publishes disclosure standards and the standard definitions for response-rate calculation. Reputable market research follows them so results are comparable and auditable.
+
+## Sources
+
+1. Cochran, W.G., *Sampling Techniques*, 3rd ed. (Wiley, 1977).
+2. Dillman, Smyth & Christian, *Internet, Phone, Mail, and Mixed-Mode Surveys: The Tailored Design Method*, 4th ed. (2014).
+3. Groves et al., *Survey Methodology*, 2nd ed. (Wiley, 2009) — total survey error.
+4. Schuman, H., & Presser, S., *Questions and Answers in Attitude Surveys* (1981) — wording/order effects.
+5. AAPOR, *Standard Definitions: Final Dispositions of Case Codes and Outcome Rates for Surveys*.
+6. Tourangeau, Rips & Rasinski, *The Psychology of Survey Response* (Cambridge, 2000).

package/research-ops/skills/market-research/scripts/ar_evaluator.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""ar_evaluator.py - Autoresearch evaluator for the market-research skill (OPT-IN).
+
+Stdlib-only. The ISOLATED bridge to engineering/autoresearch-agent. It does NOT call
+autoresearch; it is the ground-truth evaluator an autoresearch loop runs after editing
+the target market model. It reads a market-model JSON, runs market_sizer in "both" mode,
+and prints ONE metric line:
+
+    tam_divergence: <fraction>   (LOWER is better — top-down and bottoms-up should agree)
+
+Optimize a market model so the two sizing methods triangulate (reconcile assumptions),
+while the agent edits the target. The user opts in explicitly:
+    /ar:setup --domain custom --name tam-triangulation \\
+      --target market.json --eval "python3 ar_evaluator.py --target market.json" \\
+      --metric tam_divergence --direction lower
+
+Direct use:
+    python3 ar_evaluator.py --sample
+    python3 ar_evaluator.py --target market.json --profile enterprise
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import config_loader as cfg  # noqa: E402
+import market_sizer as ms  # noqa: E402
+
+METRIC = "tam_divergence"
+
+
+def main(argv: list[str] | None = None) -> int:
+    c = cfg.load_config()
+    p = argparse.ArgumentParser(description="Autoresearch evaluator: TAM triangulation divergence.")
+    p.add_argument("--target", help="path to market-model JSON (or env AR_TARGET)")
+    p.add_argument("--profile", default=None, help="overrides onboarding default_profile")
+    p.add_argument("--sample", action="store_true")
+    args = p.parse_args(argv)
+
+    profile = args.profile or c.get("default_profile", "b2b-saas")
+    if args.sample:
+        data = ms.SAMPLE
+    else:
+        target = args.target or os.environ.get("AR_TARGET")
+        if not target:
+            print("error: provide --target <market.json> or set AR_TARGET", file=sys.stderr)
+            return 2
+        try:
+            with open(target) as f:
+                data = json.load(f)
+        except (OSError, json.JSONDecodeError) as e:
+            print(f"{METRIC}: N/A")
+            print(f"error: {e}", file=sys.stderr)
+            return 1
+
+    try:
+        result = ms.size_market(data, "both", profile)
+    except ValueError as e:
+        print(f"{METRIC}: N/A")
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+    div = result.get("tam_divergence")
+    if div is None:
+        print(f"{METRIC}: N/A")
+        print("error: need both top_down and bottoms_up blocks to triangulate", file=sys.stderr)
+        return 1
+    print(f"{METRIC}: {div}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())