market-research-reports
Build evidence-traceable market research reports and assumption-driven market sizing or forecast scenarios. Use for market definition, industry and customer evidence, competitive landscapes, TAM/SAM/SOM reconciliation, forecast sensitivity, and auditable report scaffolds.
Install this skill
Works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and 70+ other harnesses.
npx skills add KalarisLabs/research-agent-skills --skill market-research-reportsuvx research-agent-skills install market-research-reportsDocumentation & Instructions
Market Research Reports
Purpose
Create decision-focused market reports whose claims, calculations, assumptions, and uncertainties can be audited. Match depth and format to the question and evidence. There is no required length, chapter count, visual count, or output format.
Do not:
- imitate or imply affiliation with a consulting, analyst, or research brand;
- invent citations, quotes, market shares, or paid-market figures;
- present TAM/SAM/SOM or a forecast as one certain truth;
- treat a framework, chart, or fluent narrative as evidence;
- provide investment, legal, antitrust, tax, accounting, or regulatory advice.
Operating principles
- Define before sizing. Fix product, customer, geography, channel, period, measure, unit, denominator, currency/base year, and taxonomy.
- Map every claim. Every factual or quantitative claim has a claim ID and exact source IDs.
- Separate statement types. Distinguish facts, estimates, calculations, forecasts, opinions, and recommendations.
- Prefer primary evidence. Use official statistics, regulator records, filed company disclosures, and transparent original studies before secondary synthesis.
- Preserve uncertainty. Retain source conflicts, revisions, scenario ranges, sensitivity, and limitations.
- Keep methods reproducible. Use local structured inputs and deterministic calculations when practical.
- Collect lawfully and ethically. No deception, PII disclosure, access circumvention, confidential material, or trade-secret acquisition.
Workflow
1. Establish the research contract
Clarify:
- decision, audience, deadline, and materiality threshold;
- formal market definition and adjacent exclusions;
- buyer, payer, user, transaction, and value-chain level;
- geography and treatment of imports, exports, and channels;
- historical period, forecast period, and retrieval cutoff;
- revenue/expenditure, gross output/value added, units, capacity, users, or another measure;
- stock/flow, gross/net, taxes, and denominator;
- currency, base year, and nominal/real/current/constant basis;
- industry and product classification with version;
- permitted data sources, primary research, confidentiality, and output format.
Ask a focused question when a missing choice would materially change the denominator or result. Otherwise state a provisional scope and proceed.
Use references/report_structure_guide.md for modular report design.
2. Build the evidence plan
Route each question to the source closest to the underlying event:
- primary law, regulator decision, official filing, or official statistic;
- original company filing or attributable first-party disclosure;
- transparent survey/study with inspectable methods;
- institutional or peer-reviewed research using identifiable primary data;
- industry association data with disclosed coverage;
- reputable secondary synthesis;
- lawfully accessed paid estimate with inspectable scope and method;
- news/commentary for leads or attributable events.
For company data, prefer the official filing system in the relevant jurisdiction. For industry, labor, prices, population, trade, and national accounts, prefer the responsible national statistical agency or central bank. For cross-country work, use harmonized World Bank, IMF, OECD, or Eurostat data only after checking definitions and original-source lineage.
Read references/official_data_sources.md before using public APIs. API rules
and limits are a dated snapshot: verify current official terms before automated
or high-volume retrieval. Never put an API key in a report or bundled script.
3. Create the source ledger
Assign stable IDs (S-001, S-002, ...). Record:
- title, publisher, URL/persistent ID, source type;
- publication date and retrieval date;
- original producer when accessed through an aggregator;
- geography, covered population, period, and vintage;
- currency, base year, price basis, measure type, unit, and denominator;
- taxonomy and version;
- preliminary/revised/final/current status;
- method, sample, imputation, suppression, and limitations;
- license/terms and lawful local snapshot path.
Use assets/source_ledger_template.csv and validate it:
python3 scripts/validate_evidence_ledger.py data/source_ledger.csv
If publication date is unavailable, record not-stated; do not guess.
4. Maintain a claims ledger
Assign IDs (C-001, ...). Keep the exact claim text, statement type, source
IDs, report location, as-of date, geography, currency/base, measure/unit,
taxonomy, revision status, confidence, calculation ID, and assumption IDs.
Rules:
- one end-of-paragraph citation does not support unrelated sentences;
- split compound claims that rely on different evidence;
- a calculation cites its inputs, not a source that never published the result;
- an aggregator and its original source are not independent corroboration;
- an interview theme is not population prevalence;
- absence of public feature evidence means
unknown, notno.
Audit mappings:
python3 scripts/audit_claim_citations.py \
data/claims.csv data/source_ledger.csv
See references/evidence_model.md.
5. Size the market as scenarios
Measurement guardrails
Give every component a disjoint coverage_key and one shared
denominator_id. Do not add:
- manufacturer revenue to distributor or end-customer spend;
- production, imports, and sales without trade/inventory reconciliation;
- parent and subsidiary revenue;
- bundles and their included components;
- gross output and value added;
- installed-base stock and annual transaction flow;
- overlapping customer or geographic segments.
Use product classifications and supply-use logic when industry codes are too broad. Preserve an unknown/residual category instead of forcing totals.
Top-down and bottom-up
Compute independently:
TAM_top = sum(disjoint in-scope component values)
TAM_bottom =
sum(customer_count
* addressable_fraction
* annual_quantity_per_customer
* price_per_unit)
Then apply scenario-specific serviceability and capture assumptions:
SAM_s = TAM * serviceable_fraction_s
SOM_s = SAM_s * obtainable_share_s
Use at least two genuinely different scenarios; a downside/base/upside set is usually useful. State horizon, constraints, evidence, and assumptions. SOM is not a guaranteed revenue forecast.
Run the deterministic calculator:
python3 scripts/calculate_market_sizing.py \
assets/market_sizing_scenarios_template.json
Report both methods, midpoint-relative gap, scope differences, sensitivity, and unresolved reconciliation. Do not average incompatible methods.
6. Forecast with explicit uncertainty
Separate observed, estimated, and forecast periods. Record series ID, frequency, units, seasonal adjustment, transformations, taxonomy breaks, retrieval date, and vintage/revisions.
For each scenario:
- provide an annual rate path or driver equations;
- state demand, price, supply, regulation, competition, capacity, and timing assumptions;
- list evidence and assumption IDs;
- identify conditions that invalidate the scenario.
Do not call scenario bounds confidence or prediction intervals. Do not assign probabilities without a validated probabilistic model and diagnostics.
Run:
python3 scripts/forecast_sensitivity.py \
assets/forecast_sensitivity_template.json
Show the range by year, endpoint sensitivity, influential assumptions, and
switching values. See references/data_analysis_patterns.md.
7. Analyze customers and primary research
For survey evidence, disclose sponsor, target population, frame, probability/non-probability design, recruitment, mode/language, field dates, unweighted sample, subgroup bases, weighting, response/participation, instrument wording, precision, processing, and limitations.
For interviews/focus groups, disclose recruitment, consent, role coverage, dates/mode, guide, coding, divergent evidence, privacy controls, and limits to generalization.
Never:
- collect more personal data than necessary;
- place direct identifiers or raw recordings in report artifacts;
- use research as disguised selling or lead generation;
- misrepresent identity/purpose;
- pressure participants to reveal employer/customer secrets;
- report qualitative mention counts as market prevalence.
Follow references/methods_and_ethics.md.
8. Analyze competitors and concentration
Define product and geographic scope from the customer perspective before selecting competitors or calculating shares. Consider non-price dimensions, channels, imports, digital/multi-sided features, innovation, and dynamic change where relevant.
Use lawful public evidence and a common product edition, geography, and as-of date. Validate a complete matrix:
python3 scripts/validate_competitor_matrix.py \
assets/competitor_feature_matrix_template.csv \
--source-ledger assets/source_ledger_template.csv
For shares, state revenue/units/capacity/users or other metric, denominator, period, residual share, and source coverage. HHI/CRn are descriptive screens, not legal conclusions. A TAM category is not automatically a relevant antitrust market.
9. Normalize units and definitions
Before combining values:
- align geography, period, stock/flow, gross/net, unit, and denominator;
- convert currencies with an identified source and rate convention;
- align base year and nominal/real basis;
- do not force chained-dollar additivity;
- preserve taxonomy versions and document concordance uncertainty;
- record every conversion as a calculation.
Check comparison groups:
python3 scripts/check_unit_consistency.py \
assets/consistency_check_template.csv
10. Draft and review
Lead with findings and uncertainty, not frameworks. Use optional frameworks only to organize questions; do not force scores or a fixed number of factors. Keep recommendations separate from evidence and include dependencies, trade-offs, decision thresholds, and disconfirming evidence.
Visuals are optional. If used, build them from validated local data and include
scope, units, source IDs, calculation ID, observed/forecast distinction, and
limitations. See references/visual_generation_guide.md.
Generate a Markdown workspace:
python3 scripts/generate_report_scaffold.py \
assets/report_manifest_template.json ./market-report-workspace
Or use the optional LaTeX assets:
assets/market_report_template.texassets/market_research.styassets/FORMATTING_GUIDE.md
Release gate
- Market boundary, taxonomy, denominator, geography, and period are explicit.
- Every factual/quantitative claim maps to exact source IDs.
- Publication/retrieval dates, revisions, method, and limitations are recorded.
- Currency/base year, nominal/real basis, stock/flow, and units are consistent.
- Top-down and bottom-up methods use disjoint coverage and are reconciled.
- TAM/SAM/SOM and forecasts are conditional scenarios with sensitivity.
- Survey/interview evidence carries method, privacy, and inference limits.
- Competitor evidence is lawful, dated, scoped, and uses
unknownhonestly. - Source conflicts and revisions remain visible.
- No fabricated/unsupported paid figures, PII, trade secrets, deceptive collection, brand impersonation, or investment-advice framing appears.
Bundled resources
References
references/report_structure_guide.md— modular report architecture.references/evidence_model.md— claim-source mapping and provenance.references/data_analysis_patterns.md— sizing, forecast, consistency, survey, and concentration methods.references/official_data_sources.md— current official source/API routing.references/methods_and_ethics.md— survey, interview, privacy, competitor, and antitrust safeguards.references/visual_generation_guide.md— optional evidence-led displays.references/sources.md— dated authoritative source ledger.
Templates and CLIs
Use the templates in assets/ as synthetic schemas, not real-world evidence.
All scripts in scripts/ are standard-library, bounded, local-only tools. They
reject oversized or malformed input, do not follow symlink inputs, do not
overwrite outputs without explicit permission, and make no network, LLM, image,
dynamic-evaluation, or pickle calls.
Agent operating procedure
- Check the environment. Collect the user's draft, data, figures and target venue before writing anything.
- Pin down the inputs. Confirm formats, identifiers and parameters from the data or the user. Ask rather than guess any value that changes the result.
- Run a small version first. Draft one section or paragraph and confirm tone, structure and terminology with the user.
- Execute the full task using the instructions and references above.
- Validate the result. Every claim traces to the user's data or a verified source; numbers match tables and figures; citations are real (
citation-verification). - Report. State what was run (versions, commands, parameters), what was checked, and what is still uncertain.
| If this happens | Do this |
|---|---|
| A claim has no supporting data or citation | Flag it in the text (e.g. [citation needed]) instead of inventing support. |
| A function, flag or endpoint in these instructions is missing in the installed version | Check the installed version's own documentation (help(), --help, official docs), adapt, and tell the user. Never invent an API. |
| A required input, identifier or parameter is ambiguous | Ask the user, or state the assumption explicitly before running. |
Integrity rules
- Never fabricate results, parameters, identifiers, citations or statistics. If something cannot be run or verified, say so plainly.
- The user is the author: never add results, references or claims they did not provide or approve.
- Treat version-specific details here as possibly outdated: confirm them against the official documentation for the installed version.
- Ask before actions that cost money, consume shared GPUs or cloud quota, touch personal or patient data, or cannot be undone.
Trigger Prompts & Evaluation Corpus
These evaluation prompts test that the agent correctly selects market-research-reports for relevant tasks and leaves it out for near misses.
Should trigger (3)
- should trigger
“Can you help me size the market for industrial IoT sensors in Germany?”
expects Should fix market definition first (product, customer, geography, period, unit, denominator, currency/base year), ask a focused question or state a provisional scope, then plan top-down and bottom-up sizing as scenarios with sourced assumptions rather than one certain figure.
- should trigger
“I've got source_ledger.csv with 14 sources and a claims.csv for my draft report on the European heat pump market. Some of the numbers come from Statista, which just repackages Eurostat data. Can you check that every claim maps to valid source IDs and tell me whether my corroboration is real?”
expects Should validate the source and claims ledgers and audit claim-to-source mappings, flag missing or unknown IDs, and note that Statista and Eurostat are not independent corroboration. It should recommend citing the original Eurostat source and keeping dates, vintage and base-year fields in the ledger.
- should trigger
“My startup is selling to dental clinics in Canada and I need to show a board how big the opportunity might be over the next 5 years, with a pessimistic and optimistic view, and which assumptions matter most. I'd rather not just quote some analyst number.”
expects Should build documented downside/base/upside scenarios with explicit annual rate paths and assumption IDs, reconcile top-down and bottom-up estimates and report the gap, and run sensitivity and switching values. It should avoid calling the bounds confidence intervals or assigning probabilities, treat SOM as a capture assumption and not a guaranteed forecast, and separate evidence from recommendations.
Near misses (2)
- near miss
“Write a Python script that scrapes Amazon product reviews for wireless earbuds and runs sentiment analysis with a transformer model, then plots sentiment by brand.”
expects Should not use the market research reports skill. It is a scraping and NLP engineering task, so it should be handled with general coding or an NLP/data-science approach, noting the terms-of-service and scraping caveats.
- near miss
“Should I buy Nvidia stock now? Give me a price target and tell me whether the semiconductor sector is overvalued.”
expects Should not use the market research reports skill. This is a request for investment advice and price prediction, which the skill excludes. A careful answer would decline to give personalized investment advice and offer general, sourced information instead.