IntermediateAlireza Rezvani

Market Research

Use Market Research for TAM, SAM and SOM market sizing before entering a new category or country. Supply market estimates, customer counts and spending assumptions to compare two sizing methods, plan survey samples and assess target segments, giving your team a clearer view of the opportunity and the assumptions behind it.

Views
0
Copies
0
Favorites
0
Editorial Score
81/100
01

What this Skill does

The Skill combines three research tasks: estimating market size, deciding how many survey responses are needed and assessing which customer segments are substantial and reachable. The supplied Python tools calculate from your inputs, while the research brief keeps the question, sources and assumptions together.

For an ecommerce team, that can support a choice between new audiences or regions before committing inventory and marketing resources. Large market totals are treated as a starting estimate, with a separate view of the customers your store could actually serve.

02

What makes it different

01

Compare two market-size estimates

Top-down sizing starts with a wider market; bottom-up sizing starts with customers and spending. Showing both exposes disagreements in penetration, frequency or customer-count assumptions before one number enters a business plan.

02

Plan samples for each reported segment

Survey planning considers confidence, error tolerance and minimum samples for each segment you want to report. A survey that is large enough overall may still be too small to compare two countries or customer groups.

03

Separate attractive segments from reachable ones

Segment scoring checks size, measurability and practical access alongside differentiation and actionability. A promising audience can be set aside when it is too small or your team has no realistic way to reach it.

04

Keep the calculations and assumptions together

Calculation outputs and the assumptions register travel together in the research brief. Teammates can revise a source estimate or customer assumption and understand why the market range changes, instead of receiving an unexplained headline figure.

03

Before you install

An agent that can read files and run Python

Use Claude Code, Codex, or OpenClaw with local file and terminal access. Have Git and Python 3 available. The inspected scripts import only standard-library modules; no pip packages, API keys, or store connection are required for the calculations.

The complete Skill directory

Keep SKILL.md, scripts/, references/, and assets/ together. Copying the instructions into a chat omits the tools they call. If market-research is already installed, back up local changes before replacing it.

Sourced inputs with one market boundary

Prepare market.json, survey.json, or segments.json using the embedded SAMPLE objects as schema examples. Define geography, year, currency, customer counts, annual spending, and evidence for each assumption. Example data is fictional B2B SaaS data.

04

Install and get started

Copy this request into Codex or Claude Code. The assistant downloads the original repository at the specified commit, installs the complete files and checks required dependencies.

  1. Open Codex or Claude Code with local file and terminal access.
  2. Copy the request below into the app you are using. The assistant will select that app’s installation directory.
  3. Check the returned path and file checks. Start a new session if needed, then ask the assistant to use the installed Skill.
Install market-research in the app I am using and carry out the file installation, not just explain it. Original repository: https://github.com/alirezarezvani/claude-skills.git Commit: 6d2f02ea077eead1bee5411a31bcc6db5a11a70c Skill folder: research-ops/skills/market-research 1. Download this exact source into a new directory. Read SKILL.md and its setup references before running any bundled scripts. Do not substitute another author’s package. 2. For Codex, use ~/.agents/skills/market-research; for Claude Code, use ~/.claude/skills/market-research. Install only for my current app. Install the complete Skill folder, including scripts, references, assets and bundled notices. Keep any root license with the installed folder. Check all destination folders first; if any already exist, report differences before replacing them. 3. Compare the source and installed file lists and hashes. Inspect documented runtimes, dependencies and required connections. Configure only the local dependencies needed for this Skill; use an isolated environment when appropriate. Ask me to complete any account login locally, without putting credentials in chat. 4. Report the source commit, actual installation path, file-check results and any remaining runtime setup. Explain how to invoke market-research in this app. Check discovery separately from file copying; start a new session if needed. Do not run production tasks or claim a successful business outcome from installation alone.
05

Original Skill.md

The complete, unchanged English SKILL.md is shown below. It is one file in an 11-file Skill package; copying this text does not install the scripts, references, or template. The Chinese guide and starter prompts are EcomAgentTools editorial adaptations.

---
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.
license: MIT
metadata:
  version: 2.9.0
  author: claude-code-skills
  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`.
06

Get started

Starter prompts for the main use cases—copy and use them directly.

01

Check the installation and save research defaults

Locate the package, inspect the four onboarding questions, and save a market profile and survey defaults. Use immediately after installation or when starting research for a different market.

Show prompt and variablesHide prompt and variables
Use the installed market-research Skill. Locate its actual directory and confirm SKILL.md, scripts/, references/, and assets/ exist. From my research project directory, run python3 <skill-directory>/scripts/onboard.py --show. Ask me to confirm [PROFILE], survey confidence, margin of error, and sizing_method=both, then save them with --scope project. Keep subsequent analysis in this project directory so it reads the same config. Do not start autoresearch.

Replace these variables

[PROFILE]
One of consumer, marketplace, b2b-saas, enterprise, hardware, or services.
02

Estimate a new category’s market size

Build two estimates from your market inputs and explain the TAM gap before recommending a planning range. Use before deciding whether a category or geography warrants further validation.

Show prompt and variablesHide prompt and variables
Use the installed market-research Skill for [MARKET] using [MARKET_JSON] and [SOURCES]. Check every top_down and bottoms_up field against market_sizer.py SAMPLE, including geography, annual period, currency, and fraction units. Ask for missing inputs rather than accepting zero defaults. Run python3 <skill-directory>/scripts/market_sizer.py --input [MARKET_JSON] --method both --profile consumer --output json. Report both TAM/SAM/SOM sets, TAM divergence, assumptions, sources, and unresolved differences. Do not change evidence simply to reduce the gap.

Replace these variables

[MARKET]
Product category, geography, channel, and year.
[MARKET_JSON]
Path to a complete market JSON input file.
[SOURCES]
Sources and dates for market value, customer counts, annual spending, and shares.
03

Budget a survey by customer segment

Calculate the overall sample and each group’s quota from a survey specification. Use when results must be reported separately for several customer groups.

Show prompt and variablesHide prompt and variables
Use the installed market-research Skill to review [SURVEY_JSON]. Check population, confidence, margin_of_error, expected_proportion, segment_moe, and segments with population_share values that sum to 1. With --input, survey values must be in the JSON; CLI --confidence and --moe do not override it in this version. Run python3 <skill-directory>/scripts/sample_size_planner.py --input [SURVEY_JSON] --output json. Explain overall FPC, per-segment floors, recommended quotas, and their sum. Check feasibility against each segment population. Estimate invitations separately using [RESPONSE_RATE], and flag coverage and non-response bias.

Replace these variables

[SURVEY_JSON]
Path to survey parameters and segment definitions.
[RESPONSE_RATE]
Evidence-based expected completion rate, for invitation planning only.
04

Decide which customer segments to test

Apply the five scoring criteria and inspect the reasons for TARGET, WATCH, and DROP. Use when candidate segments have documented needs, size, and acquisition channels.

Show prompt and variablesHide prompt and variables
Use the installed market-research Skill with [SEGMENTS_JSON] and [EVIDENCE]. Check that each segment has all five 0–100 scores: measurable, substantial, accessible, differentiable, actionable. Do not invent scores for missing evidence. Run python3 <skill-directory>/scripts/segmentation_scorer.py --input [SEGMENTS_JSON] --profile consumer --output json. Explain the weighted score and the substantial/accessibility gates. For each TARGET or WATCH, propose one test within [BUDGET]; do not treat a score as proven demand.

Replace these variables

[SEGMENTS_JSON]
Path to candidate segments and their five scores.
[EVIDENCE]
Source material supporting each score.
[BUDGET]
Budget and time available for validation.
05

Assemble a research brief for a decision

Combine the calculations, source notes, and assumptions using the included template. Use when the team needs to decide whether to proceed, test, or defer.

Show prompt and variablesHide prompt and variables
Use the installed market-research Skill and assets/market_research_brief_template.md to assemble [RESULT_FILES] for [DECISION]. Preserve both sizing methods and their disagreement. Include any survey quotas, segment verdicts, public competitive evidence, source dates, assumptions register, and confidence statement. Mark unused sections as not applicable. Separate calculated results from judgment, and name the evidence still needed before committing budget.

Replace these variables

[RESULT_FILES]
Paths to calculation outputs and source notes.
[DECISION]
The specific category, market, or research-budget decision.
07

Worked example: Turn market-size assumptions into a research plan

A synthetic merchant has 10,000 permissioned research contacts and explicit assumptions for commuter and desk-use segments. The task combines market sizing, segment selection and survey recruitment planning.

Steps and prompt

  1. Prepare the attached business materials, preserving amounts, units, dates and metric definitions.
  2. Before funding expansion, estimate the addressable market from our supplied market and segment assumptions. Show top-down and bottom-up TAM, SAM and SOM, explain any mismatch, rank target segments and design a proportionate survey with sample and invitation counts. Deliver the questionnaire and a decision brief that makes the assumptions visible.
  3. Submit the exact prompt below. Read the primary deliverable on the right and download all deliverables for the team handoff.

Case input files: business-inputs.zip

Use the market-research Skill.

Before funding expansion, estimate the addressable market from our supplied market and segment assumptions. Show top-down and bottom-up TAM, SAM and SOM, explain any mismatch, rank target segments and design a proportionate survey with sample and invitation counts. Deliver the questionnaire and a decision brief that makes the assumptions visible.

The attached business materials are:
- inputs/brief.md
- inputs/evidence.md
- inputs/market.json
- inputs/merchant.json
- inputs/segments.json
- inputs/survey.json

Deliver a complete result.md report that the operations team can read, plus any finished files needed for this task. Keep supporting calculations and evidence with the deliverables. Write the report in English; use the requested target language for customer-facing copy. The business datasets are fictional examples unless the brief explicitly names a live public website.

What the run produced

The primary file produced by this prompt is shown below in its original language.

HarborMug: US audience-validation decision brief

Recommend funding a bounded US audience-validation study before committing to expansion. Prioritize commuters, retain desk-first users as a comparison group, and exclude international expansion from this decision. Mia should prepare the study; Alex decides funding. No dollar research budget can be approved from these materials because recruitment and fielding costs were not supplied.

Data note: All business inputs and competitor observations are synthetic, unverified planning assumptions. No customers were contacted, no fieldwork occurred, and no business improvement was measured. Arithmetic is deterministic; empirical confidence is low.

Addressable market and funding implication

The planning window is one year, geography is the US, and the category assumes one 500ml mug per annual buyer at $24. Figures represent product revenue in USD/year, excluding taxes, shipping and refunds. TAM covers the full defined category; SAM is the assumed 40% that HarborMug can serve; SOM is assumed demand capped by planned supply.

LayerTop-down calculationBottom-up calculationAnnual result, each method
TAME1 category spend: $48mE2: 2m buyers × $24$48m
SAM$48m × 40%2m × 40% × $24$19.2m
SOM before capacity cap$19.2m × 1% reachable share800,000 serviceable buyers × 1% adoption × $24$192,000
SOM after capacity capmin($192,000, 8,000 × $24)min(8,000 demand units, 8,000 capacity units) × $24$192,000

Sources: supplied E1, E2 and E4, preserved in source evidence. The original sizing tool computes percentage-based SOM but does not implement a separate capacity input. The explicit cap above closes that gap. These are scenarios, not sales forecasts or profit estimates.

TAM divergence is |top-down − bottom-up| / top-down = 0%; SAM and SOM also match. Both views share category scope and price, and the buyer assumption was deliberately aligned with spend. This is arithmetic consistency, not independent validation. Do not average them or treat their agreement as stronger evidence. The consumer script allows 40% TAM divergence, but the decision brief requires ±20% planning tolerance; use the stricter 20% reconciliation threshold for this funding decision. Neither threshold is a statistical confidence interval.

The 1% obtainable-share assumption implies 8,000 buyers and consumes 100% of planned annual capacity. It has no demonstrated acquisition or conversion basis. The 8,000-unit limit is a new planning assumption, independent of current weekly orders; current sales do not establish expansion capacity or demand. A 60/40 split in research contacts does not establish national segment shares, so no national commuter or desk revenue allocation is defensible yet.

Adoption of the 800,000 serviceable buyersDemand unitsUnits after supply capProduct revenue
0.5%4,0004,000$96,000
1.0%8,0008,000$192,000
1.5%12,0008,000$192,000

These are illustrative sensitivities, not probability bounds. More demand above 1% cannot increase revenue under the stated capacity. Validate category buyer counts, purchase frequency, the serviceable fraction and reachable demand before using the base case to fund supply expansion.

Ranked target segments

The original Kotler scorer weights measurable 15%, substantial 25%, accessible 25%, differentiable 20%, and actionable 15%. Substantiality and accessibility must each reach 40/100. With both gates passed, a weighted score of at least 65 yields TARGET; otherwise WATCH. Scores are E5 analyst judgments, not survey findings; the consumer profile leaves substantiality unchanged.

PrioritySegmentMeasurableSubstantialAccessibleDifferentiableActionableWeighted scoreVerdict
1Commuter858080758580.5TARGET
2Desk-first807065708071.8TARGET
ExcludeInternational707520602049.2DROP: accessibility

Commuters have a portable-drinkware need and a consented-list channel; study portability, spill concerns and existing alternatives. Desk-first users have a workspace-drinkware need and the same channel, with weaker assumed accessibility; retain them to test whether needs and response actually differ. These needs are hypotheses to test, not established product advantages. International fails the channel gate and is outside domestic fulfillment. Its composite score cannot override that gate. The listed contact counts measure the research frame, not segment profitability or national market size.

E6 supplies fictional $22 and $30 alternatives. HarborMug's $24 item price sits between them, but there is no like-for-like feature or delivered-price evidence. Five Forces assumptions are high rivalry, high substitution (including cups already owned), moderate entry threat, moderate supplier power and high buyer power. This makes replacement motivation and delivered-price acceptance central questions; it does not establish competitive advantage. No real brand or website was inspected.

Survey design and recruitment requirement

Use randomized online invitations without replacement within the two mutually exclusive primary-use strata. The eligible consented frame is 10,000 US contacts: 6,000 commuters and 4,000 desk-first users (E3). These frame proportions are not US population weights. The intended estimands are frame-level proportions and within-group proportions.

At 95% confidence, z = 1.96 and conservative p = 0.5:

  • Unadjusted n₀ = z²p(1−p)/e² = 384.16 at e = 0.05; round up to 385.
  • Finite-population n = n₀ / [1 + (n₀−1)/N] = 369.984 for N = 10,000; round up to 370.
  • At e = 0.08, each group needs 150.0625 before rounding, or 151 completes. The original planner conservatively applies no group-level FPC.
GroupFrameProportional allocation of 370Original planner's group floorFunded completesInvitations at 25% usable completion
Commuter6,000222151222888
Desk-first4,000148151151604
Total10,000370—3731,492

Retain the original planner's conservative 373-complete design. Group-specific FPC would reduce the individual floors to 147 and 145, but this is not needed to make the main plan feasible. Desk users receive three additional completes to protect the original floor. Invitation counts are ceil(completes / 0.25); they are expected recruitment requirements, not guaranteed yields. They assume 25% of invited contacts become eligible, usable completed interviews. If the supplied response assumption refers only to survey starts, more invitations will be needed.

The slightly disproportionate allocation requires overall estimates of 0.6 × commuter estimate + 0.4 × desk estimate, rather than an unweighted pooled percentage. Under random-response assumptions, the finite-population stratified variance gives worst-case overall margin ±4.98 percentage points; commuter ±6.46 points and desk ±7.82 points. This satisfies the targets. These are pointwise intervals for proportions, not power guarantees for differences, small cross-tabs or multiple comparisons.

Randomize the invitation order within each frame stratum and release controlled batches. Monitor eligibility, delivery failures, partials and completes separately. Use remaining randomly ordered contacts for top-ups if yield falls short; never exceed the eligible frame or count repeated invitations as new people. Log recruitment dispositions and actual completed-interview yield by stratum. Reconcile changed primary-use classifications before claiming the planned precision.

The finite-population correction and nominal precision apply to this frame under the stated sampling assumptions. Nonresponse may invalidate representativeness even when quotas are achieved. Compare available frame characteristics between respondents and nonrespondents, document coverage and response differences, and disclose weighting and denominators. This consented contact list cannot validate national buyer counts or national 1% adoption by itself. Smaller item-level response counts require recalculated intervals; do not claim the full-sample margin for skipped questions.

Completed questionnaire and analysis specification

The complete customer-facing instrument, invitation copy, routing and pretest instructions are in questionnaire.md, ready for cognitive pretesting. English is used because no different target language was supplied.

Its sequence is consent → US eligibility → exclusive primary-use classification → purchases and usage → existing substitutes and unmet needs → selection priorities → category purchase intent → product concept with full single-unit shipping cost → product intent → likely alternative → reasons. The concept states $24 plus $5 shipping ($29 before tax), care restrictions and delivery timing. It makes no unsupported health or environmental claims.

The primary outputs will be Q9 stated purchase likelihood by group and Q10 preferred alternative, alongside Q3 purchase frequency and Q6 unmet needs. Ask behavior and needs before showing the brand concept to reduce priming. Randomize unordered options, keep ordered scales intact, and preserve neutral and Not sure responses. The instrument does not equate stated intent with realized adoption or attempt to optimize price from a single price point.

Before launch, conduct 6–8 proposed cognitive interviews across both groups and test mobile display, eligibility exits and option randomization. Keep pretest answers out of the main analytic sample. No pretest or survey responses exist yet. After fielding, report group denominators, missing answers, weighted frame estimates, intervals and exclusions. Do not infer that groups differ solely because one ranks higher; test the difference with its own uncertainty.

Boundary checks: smaller frame and conflicting buyer count

The supplied boundary changes the buyer estimate to 1m and the frame to 100 eligible contacts split 90/10. These changes expose decision-relevant failures rather than a new recommended base case.

LayerTop-down, unchangedBottom-up, 1m buyers
TAM$48m$24m = 1m × $24
SAM$19.2m$9.6m = $24m × 40%
SOM, capped at 8,000 units$192,000 (8,000 units)$96,000 (4,000 units)

TAM divergence is 50%, exceeding both the script's 40% tolerance and the decision's 20% tolerance. SAM and SOM also differ by 50%. Reconciliation requires checking scope, annual buyer counts and spend: $48m at $24 implies 2m annual buyers, whereas 1m buyers at $24 implies $24m. Do not average to $36m, silently change assumptions, or claim either view is validated. Hold expansion until evidence resolves which premise is credible.

For the 100-person frame, the original survey planner reports 80 overall completes but recommends 302 after applying two uncorrected 151-person floors. That result exceeds the frame and is infeasible. Group FPC yields floors of 57 out of 90 commuters and 10 out of 10 desk users. Those floors total 67 and do not alone ensure overall ±5%. A feasible complete-response design would be 72 commuters plus all 10 desk users (82 total); the 90/10 weighted worst-case overall margin is about ±4.67 points, with the desk result a census of its frame group.

At 25% yield, inviting the entire 100-person frame produces only 25 expected completes (22.5 commuters and 2.5 desk users). Even the individual FPC floors imply 228 commuter and 40 desk invitations, beyond the available 90 and 10. Do not issue impossible invitation quotas or label the study powered. Seek much higher participation, expand a legitimate eligible frame, or reduce precision and treat the work as exploratory. A full census invitation alone does not make nonrespondents observed.

Assumptions, evidence and decision gates

EvidencePlanning assumptionConfidence and action before expansion
E1$48m annual US category spend; one 500ml mug per buyerLow; verify category definition and independently sourced spend
E22m annual buyers, $24 spend, 40% serviceableLow; verify buyer count and frequency; define which needs and channels justify 40%
E310,000 exclusive consented contacts, 60/40 split, 25% usable yieldLow; verify eligible frame and classifications; monitor actual response and nonresponse
E41% reachable adoption, 8,000 annual supply unitsLow; validate acquisition and purchase behavior separately from supply readiness
E5Five segment scores and known channelsLow; validate distinct needs, reachability and economics; do not treat scores as measurements
E6Two fictional prices and Five Forces judgmentsLow; no independent competitor evidence; assess comparable delivered offers before commitment
Merchant terms$24 item, $5 single-unit shipping, domestic delivery, hand washingSupplied assumptions; include them in concept testing because they affect purchase decisions

Alex should authorize only the validation stage once Mia has costed 373 usable completes, 1,492 initial invitations and the separate pretest. No cost-per-complete or research budget ceiling is supplied, so this brief establishes quantities rather than a fabricated spend request.

For the next expansion review, require: independently checked sizing inputs reconciled within the ±20% decision tolerance; both survey group quotas or an explicitly revised precision statement; documented nonresponse and frame limitations; evidence that needs distinguish the two groups; and an acquisition/economic case plus confirmed capacity for the proposed volume. Survey intent is an input to that case, not a conversion forecast. Profitability, acceptable acquisition cost and investment-return thresholds are not supplied, so a numeric expansion go/no-go threshold cannot responsibly be invented.

The immediate decision is therefore to validate commuters first while preserving the desk comparison, withhold international expansion, and defer expansion funding until the demand and economic gaps are resolved.

Supporting deliverables

Market sizing, survey planner, segment ranking, boundary tool results, calculation checks and recomputable calculations preserve the arithmetic. Bundled source files preserve the brief, evidence and three model inputs. Method follows the supplied market-sizing canon, survey-methodology reference (Cochran FPC, total survey error, neutral wording and pretesting), and segmentation/competitive-intelligence reference (Kotler gates and Five Forces); these are methodological references, not external validation of the business inputs.

Merchant business data is synthetic. Website observations, when present, come from the public URLs listed in the report.

08

Risks and operating notes

Validate inputs before trusting a result

The sizing and segmentation scripts default some missing values to zero; sizing can also fall back to embedded sample data when no input file is supplied. Validate complete inputs and always pass --input for real work. The human sizing display uses a dollar sign, so label other currencies explicitly in JSON-based reports.

Sample size does not remove survey bias

The planner estimates completed responses for proportions. It does not send surveys, recruit respondents, correct coverage or non-response bias, or validate that quotas fit small populations. With JSON input, edit survey parameters in the file itself.

Onboarding changes local configuration

onboard.py saves globally under ~/.config/research-ops/ or under the current project with --scope project. Project config is read from the process working directory. Inspect existing settings before overwriting or resetting them. The calculation scripts contain no store API integration.

Autoresearch is optional and can change assumptions

The separate autoresearch-agent integration can edit market.json to reduce the TAM gap. It is not installed by copying this Skill alone. A smaller gap does not validate the sources; preserve the original data and review each proposed assumption change.

Frequently asked questions

Can I use this by pasting SKILL.md into chat?

The instructions can be read in chat, but the documented workflow requires the full Skill folder and local Python execution. Install scripts, references, and assets with SKILL.md.

Do I need API keys or a store connection?

The included calculations use Python’s standard library and local JSON files. They contain no store API integration. Your agent subscription or model usage is separate.

Does the Claude Code plugin install only Market Research?

No. research-ops-skills is a broader plugin containing Market Research and other research skills. Use the manual single-folder method for this Skill alone.

Which version was reviewed?

The Skill declares 2.9.0 at commit 6d2f02ea077e. The containing plugin declares 2.14.1. Marketplace installation may retrieve a newer version.

Does it find winning products or collect research automatically?

You supply market values, customer counts, survey parameters, and segment scores with supporting sources. The Skill calculates and structures the evidence; it does not prove demand or collect survey responses.

No reviews yet.

Leave a review

Rate every dimension, then share your real experience.

Task effectiveness
Setup and ease of use
Reliability and guardrails
Documentation clarity
Time to first useful result
Author / maintainer

Alireza Rezvani

Maintainer of the claude-skills open-source library. Market Research is one Skill in its Research Ops collection.