market-sizing

Market Sizing

The goal of this skill is not to manufacture precise illusions, but when the market is uncertain, to establish a magnitude-level judgment of size that can continue to be developed in Excel, based on a clear market definition, verifiable data, and a self-consistent formula chain.

Working principles

• Define the market first, then find data, then build the formula. When the market boundary is unclear, do not start calculating.
• Excel is the core deliverable, and all key TAM/SAM/SOM values must be carried by formulas; Markdown only explains the formulas, sources, and judgments.
• The first page of Excel must be the 核心结论 overview page: use one page to show the year-by-year TAM/SAM/SOM for the next 5 years, which markets make up TAM, the yearly size of each market, and a one-sentence judgment.
• Assumptions can be made, but steps cannot be skipped. Ratios, penetration rates, market shares, adoption rates, etc. must have their sources, analogies, constraints, or derivation logic written out.
• Do not use Monte Carlo, and do not output HTML/UI. Sensitivity is expressed through deterministic scenarios and key-driver tests in Excel.
• Do not attach meaningless "low credibility" labels to necessary but imperfect data. The key judgments are: is this the best currently available data? How is it transformed into the formula? Which conclusions are most affected by it?
• Cross-validation is used to discover differences in definitions, not to forcibly tune parameters so that two results agree.

Required reading reference

• references/methodology.md: First principles, formula chains, and assumption discipline.
• references/data_sources.md: Data source hierarchy, source card, and common API routes.
• references/fermi_patterns.md: Decomposition patterns such as population, institutions, substitution, value chain, and value-based.
• references/industry_templates.md: Common variables for SaaS, Marketplace, Consumer, B2B, and Hardware.

Standard process

1. Lock down the market boundary

Must be clear:

• Product/service: what is included, what is excluded.
• Geographic scope: country, region, city, or global definition.
• Customer/user: B2B/B2C, segment, institution type, purchasing entity.
• Time definition: base year, forecast period, current/nominal prices, annualized/one-time.
• Unit: amount, sales volume, number of users, number of devices, capacity, or other.

If the boundary has two reasonable interpretations, split them into two definitions first; do not mix them into one number.

2. Choose the calculation architecture

Prefer methods that can explain the market formation mechanism:

• Top-down: industry total -> segment definition -> serviceable scope.
• Bottom-up: number of customers/users/devices -> adoption rate/frequency -> unit price/ARPU.
• Substitution: existing market -> substitution rate -> price or value adjustment.
• Value-chain: end market -> share of value segment -> serviceable portion.
• Value-based: number of target subjects -> problem frequency/loss/benefit -> willingness-to-pay ratio.

The common approach is a main model + one side check. The side check can be very rough, but it must be able to explain whether the result is in a reasonable magnitude.

3. Build source cards

Every piece of data entering the model must be traceable to a source card:

Field	Requirement
source_id	Stable ID, such as SRC-001
provider	Data provider
dataset_or_title	Dataset, report, or page name
metric	Metric used
geography / period / unit	Caliber
value_or_path	Value or extraction path
url_or_endpoint	URL/API endpoint/file path
accessed_at	Access date
transform_note	How to clean, convert, filter
used_in	Used for which assumption or formula

4. Write assumption ledger

Each assumption must contain at least:

{
    "key": "pene_rate",
    "name": "目标市场渗透率",
    "numeric_value": 0.20,
    "unit": "%",
    "source_ref": "SRC-003",
    "logic": "甲市场 A/B 渗透率约 60%/40%；乙市场更适合 B 的低部署成本，同时面临 C 替代冲击，且当前教育成本更高，所以基准假设取 20%。",
    "used_in": "TAM"
}

No "bare ratios":pene_rate = 5% Assumptions like this without context cannot enter the final model.

5. Generate Excel model

Use scripts/report_generator.py：

from scripts.report_generator import MarketSizingData, ReportGenerator

data = MarketSizingData(
    market_name="中国某新兴服务市场",
    geography="中国大陆",
    base_year=2026,
    forecast_years=5,
    tam=9.6,
    sam=5.76,
    som=0.288,
    unit="亿元",
    cagr=0.08,
    market_definition={
        "产品/服务": {"in": "目标服务年费", "out": "硬件一次性收入"},
        "地理": {"in": "中国大陆", "out": "港澳台及海外"},
    },
    market_segments=[
        {
            "name": "核心场景 A",
            "base_value": 6.0,
            "growth_rate": 0.10,
            "logic": "由对象数、采用率、年费三项相乘得到，代表最大组成市场。",
        },
        {
            "name": "验证场景 B",
            "base_value": 3.6,
            "growth_rate": 0.05,
            "logic": "由相邻场景 proxy 推导，体量较小但更适合早期验证。",
        },
    ],
    source_cards=[
        {
            "source_id": "SRC-001",
            "provider": "World Bank",
            "dataset_or_title": "Population, total",
            "metric": "SP.POP.TOTL",
            "geography": "China",
            "period": "2024",
            "unit": "people",
            "value_or_path": "1.408B",
            "url_or_endpoint": "https://api.worldbank.org/v2/country/CN/indicator/SP.POP.TOTL",
            "accessed_at": "2026-06-24",
            "transform_note": "换算为亿人后进入 base_pop",
            "used_in": "base_pop",
        },
        {
            "source_id": "SRC-002",
            "provider": "内部筛选逻辑",
            "dataset_or_title": "目标人群筛选假设",
            "metric": "核心人群占比",
            "geography": "中国大陆",
            "period": "基准年",
            "unit": "%",
            "value_or_path": "40%",
            "url_or_endpoint": "logic-only",
            "accessed_at": "2026-06-24",
            "transform_note": "按年龄、收入和使用场景三层筛选。",
            "used_in": "core_pop_pct",
        },
        {
            "source_id": "SRC-003",
            "provider": "Comparable market scan",
            "dataset_or_title": "相邻市场渗透率对比",
            "metric": "penetration benchmark",
            "geography": "中国大陆",
            "period": "latest available",
            "unit": "%",
            "value_or_path": "相邻市场约 40%",
            "url_or_endpoint": "manual research notes",
            "accessed_at": "2026-06-24",
            "transform_note": "因教育成本和替代品冲击下调至 20%。",
            "used_in": "pene_rate",
        },
        {
            "source_id": "SRC-004",
            "provider": "业务机制假设",
            "dataset_or_title": "购买频次假设",
            "metric": "年购买频次",
            "geography": "中国大陆",
            "period": "基准年",
            "unit": "次/年",
            "value_or_path": "12",
            "url_or_endpoint": "logic-only",
            "accessed_at": "2026-06-24",
            "transform_note": "按月度订阅或月度复购处理。",
            "used_in": "freq",
        },
        {
            "source_id": "SRC-005",
            "provider": "公开价格页/价格带",
            "dataset_or_title": "目标服务价格假设",
            "metric": "单次价格",
            "geography": "中国大陆",
            "period": "基准年",
            "unit": "元",
            "value_or_path": "100",
            "url_or_endpoint": "manual pricing notes",
            "accessed_at": "2026-06-24",
            "transform_note": "取公开价格带中位数。",
            "used_in": "price",
        }
    ],
    assumptions=[
        {"key": "base_pop", "name": "基础人口", "numeric_value": 1.0, "unit": "亿人", "source_ref": "SRC-001", "logic": "只计入目标城市人群，按总人口筛选后换算。"},
        {"key": "core_pop_pct", "name": "核心人群占比", "numeric_value": 0.40, "unit": "%", "source_ref": "SRC-002", "logic": "按年龄、收入和场景三层筛选得到。"},
        {"key": "pene_rate", "name": "付费渗透率", "numeric_value": 0.20, "unit": "%", "source_ref": "SRC-003", "logic": "参考相邻市场 40% 渗透率，并因教育成本和替代品冲击折半。"},
        {"key": "freq", "name": "年购买频次", "numeric_value": 12, "unit": "次/年", "source_ref": "SRC-004", "logic": "按月度订阅/复购频率处理。"},
        {"key": "price", "name": "单次价格", "numeric_value": 100, "unit": "元", "source_ref": "SRC-005", "logic": "参考公开价格带的中位数。"},
        {"key": "sam_ratio", "name": "可服务比例", "numeric_value": 0.60, "unit": "%", "logic": "扣除非目标渠道、地域和暂不可服务客户。"},
        {"key": "som_share", "name": "年度可获取份额", "numeric_value": 0.05, "unit": "%", "logic": "按目标进入节奏、销售产能和竞品份额推导。"},
        {"key": "cagr", "name": "年增长率", "numeric_value": 0.08, "unit": "%", "logic": "由用户增长、价格变化和渗透率提升合成。"},
    ],
)

ReportGenerator().generate(data, output_dir="./output", formats=["xlsx", "md"])

The default workbook contains:

1. 核心结论: the first page for the user, showing year-by-year TAM/SAM/SOM, TAM composition, final-year share, and a one-sentence judgment.
2. Market_Definition: market boundary, geography, customers, time, and unit calibers.
3. Source_Cards: all data sources and conversion explanations that enter the model.
4. Assumptions: all adjustable assumptions and logic。
5. Calculation_Model: intermediate formula chain.
6. TAM_SAM_SOM: annual TAM/SAM/SOM details, must be single-year caliber, not 5-year total.
7. Checks: formula hierarchy, source, logic, units, and composition total check.

6. Deliver Markdown memo

The Markdown must answer:

• What are the TAM/SAM/SOM for each of the next 5 years; cannot only write the forecast period total or the final-year figure.
• Which markets make up TAM, how large is each market year by year, and what is the final-year share.
• What the market boundary is.
• What the core formula chain is.
• Which data come from source cards, which are derivations, and which are assumptions.
• How TAM/SAM/SOM are derived from formulas.
• Whether the side check supports this magnitude.
• Which variables can most change the conclusion, and which input cell in Excel they correspond to.

Quality gate

Must check before completion:

• There are no Monte Carlo, HTML, Plotly, or display UI requirements as deliverables.
• There is 核心结论 a first page, and the first page does not pile up process, only core readings, annual table, market composition, and a one-sentence judgment.
• TAM/SAM/SOM are year-by-year single-year caliber; 5-year cumulative values must not be used to pass off as annual market size.
• If TAM is composed of multiple sub-markets, the composition items must total back to total TAM; if not, the caliber difference must be explained and noted in Checks.
• Key Excel output cells are formulas, not manually entered static values.
• All ratios, penetration rates, adoption rates, and market shares have logic。
• in the assumptions, source_ref can be found in the source card, or it is clearly explained why only logical assumptions can be used.
• TAM >= SAM >= SOM; if this does not hold, the caliber must be explained, otherwise the model must be corrected.
• Unit conversions are traceable, for example people, hundred million people, yuan, hundred million yuan cannot be mixed.
• When the side check differs greatly from the main model, report the source of the difference, rather than changing assumptions to get closer to the result.

Common errors

• Directly writing "penetration rate 5%" without analogous markets, competitive constraints, adoption path, or sales capacity logic.
• Treating the total market in an industry report directly as your own SAM.
• Only marking "data uncertain" without explaining how it affects the formula.
• Outputting complex charts to look professional, without leaving an editable, traceable Excel model.
• Using HTML/Monte Carlo output from old scripts or old examples.