Fundamental Context

Gather fundamental context for: $ARGUMENTS

Overview

Implementation status: code-backed
Local entry script: <bundle-root>/fundamental-context/run.py
Primary purpose: add best-effort growth, earnings, institution, capital-flow, and dragon-tiger context around one symbol without pretending complete coverage
Research layer: fundamental data collection (Stage 2: Data Collection & Quality Assurance, Stage 3: Data Cleaning & Normalization, Stage 4: Feature Engineering - Fundamental subset)
Workflow stages: stage 2 Data Collection & Quality Assurance and stage 3 Data Cleaning & Normalization for non-price data
Local executor guarantee: query the current adapter set, surface status fields and source chains, and return partial blocks rather than crash on unsupported paths

Use When

The user wants deeper non-price context after or alongside market analysis.
The user wants capital-flow or dragon-tiger hints before forming a view.
The user wants a compact fundamental block without the full narrative layer.

Do Not Use When

The user only wants price or technical interpretation. Use market-analyze or technical-scan.
The user wants the full report bundle. Use market-brief.
The user wants a reusable multi-block market snapshot. Use stock-data.
The user expects full point-in-time fundamental warehousing or guaranteed cross-provider completeness. This skill does not guarantee that locally.

Inputs

Normal case: one stock symbol.
If symbol is omitted, the skill may reuse last_symbol from the same execution context.
Capability note:
- richer results depend on the optional provider stack being available
- current blocks are adapter-driven and best-effort
- the agent should say whether the request requires strict as-of correctness that this local path may not fully guarantee

Execution

Step 1: Define fundamental data requirements

Before collecting fundamental data, clarify what is needed:

Fundamental data categories:

Financial statements (income, balance sheet, cash flow)
Growth metrics (revenue, earnings, margins)
Valuation metrics (P/E, P/B, P/S, EV/EBITDA)
Profitability metrics (ROE, ROA, gross margin, net margin)
Capital structure (debt/equity, interest coverage)
Institutional ownership and changes
Capital flow (northbound, margin trading, dragon-tiger)
Sector and industry classification

Data quality requirements:

Point-in-time correctness (no look-ahead bias)
Restatement handling (use as-reported or as-restated consistently)
Reporting lag (announcement date vs. period end date)
Fiscal period alignment (quarterly, annual, TTM)
Unit consistency (yuan, millions, billions)

A-share specific requirements:

CSRC industry classification
ST/*ST status and history
Suspension history and reasons
Dragon-tiger list appearances (institutional vs. retail)
Northbound (Stock Connect) flow
Margin trading balance and changes
Pledge ratio (share pledging by major shareholders)

Step 2: Collect fundamental data with status tracking

Run the local executor and track data availability:

python3 <bundle-root>/fundamental-context/run.py <symbol>

Status model interpretation:

ok: Adapter returned complete and meaningful block
partial: Only some expected fields available (specify which)
not_supported: Local path does not currently support the block
stale: Data available but outdated (specify age)
error: Adapter failed (specify error type)

For each data block, document:

Status (ok/partial/not_supported/stale/error)
Source chain (which provider/adapter)
Data freshness (as-of date)
Completeness (% of expected fields present)
Known limitations (missing fields, stale data, etc.)

Step 3: Validate and clean fundamental data

Apply systematic validation and cleaning:

Financial Statement Validation

Income statement checks:

Revenue >= 0 (negative revenue is rare, flag for investigation)
Gross profit <= Revenue (gross margin <= 100%)
Operating profit consistency (revenue - COGS - opex)
Net income consistency (operating profit + non-operating - tax)
EPS calculation: net income / weighted average shares

Balance sheet checks:

Assets = Liabilities + Equity (accounting identity)
Current assets >= 0, Current liabilities >= 0
Total equity can be negative (flag as distressed)
Book value per share: total equity / shares outstanding
Working capital: current assets - current liabilities

Cash flow checks:

Operating cash flow vs. net income (quality of earnings)
Free cash flow: operating CF - capex
Cash flow from financing (debt issuance, equity issuance, dividends)
Cash balance change = sum of three cash flow categories

Cross-statement validation:

Net income (income statement) flows to equity (balance sheet)
Depreciation (income statement) flows to accumulated depreciation (balance sheet)
Capex (cash flow) flows to PP&E (balance sheet)
Dividends (cash flow) reduce retained earnings (balance sheet)

Growth Metrics Calculation

Revenue growth:

YoY growth: (revenue_t - revenue_{t-4}) / revenue_{t-4} (quarterly)
QoQ growth: (revenue_t - revenue_{t-1}) / revenue_{t-1}
CAGR: (revenue_latest / revenue_earliest)^(1/years) - 1
Growth consistency: % of quarters with positive YoY growth

Earnings growth:

EPS growth YoY, QoQ, CAGR (same formulas as revenue)
Earnings surprise: (actual EPS - consensus EPS) / |consensus EPS|
Earnings quality: operating CF / net income (>1 is good)

Margin trends:

Gross margin: (revenue - COGS) / revenue
Operating margin: operating profit / revenue
Net margin: net income / revenue
Margin expansion/contraction over time

Valuation Metrics Calculation

Price multiples:

P/E ratio: price / EPS (use TTM or forward)
P/B ratio: price / book value per share
P/S ratio: market cap / revenue
EV/EBITDA: enterprise value / EBITDA

Valuation context:

Historical percentile (current P/E vs. 5-year range)
Sector relative (P/E vs. sector median)
Growth-adjusted (PEG ratio: P/E / earnings growth rate)
Quality-adjusted (P/E vs. ROE, margin, cash flow quality)

A-share valuation considerations:

A-share vs. H-share premium/discount (if dual-listed)
Sector rotation effects (growth vs. value cycles)
Policy sensitivity (regulatory risk premium)
Liquidity premium (large cap vs. small cap)

Profitability and Efficiency Metrics

Return metrics:

ROE: net income / average equity
ROA: net income / average assets
ROIC: NOPAT / invested capital
ROE decomposition (DuPont): net margin × asset turnover × equity multiplier

Efficiency metrics:

Asset turnover: revenue / average assets
Inventory turnover: COGS / average inventory
Receivables turnover: revenue / average receivables
Days sales outstanding (DSO): 365 / receivables turnover

Capital structure:

Debt/Equity ratio
Interest coverage: EBIT / interest expense
Net debt: total debt - cash
Net debt / EBITDA (leverage ratio)

Institutional and Capital Flow Analysis

Institutional ownership:

Total institutional ownership %
Changes in institutional ownership (QoQ)
Top institutional holders and their changes
Foreign institutional ownership (QFII, RQFII)

Northbound (Stock Connect) flow:

Cumulative northbound holdings
Daily/weekly/monthly northbound flow
Northbound ownership % of float
Northbound flow vs. price correlation

Margin trading:

Margin trading balance (融资余额)
Margin trading balance change (daily, weekly)
Margin trading balance / market cap
Margin trading sentiment (increasing = bullish, decreasing = bearish)

Dragon-tiger list (龙虎榜):

Appearance frequency (how often on list)
Net buying by institutions vs. retail
Hot money (游资) activity patterns
Institutional seat identification (券商营业部)

Share pledging:

Total shares pledged by major shareholders
Pledge ratio (pledged shares / total shares)
Pledge risk (if stock price falls, forced liquidation risk)
Changes in pledge ratio over time

Step 4: Synthesize fundamental context

Organize fundamental data into coherent narrative:

Part 1: Business and Financial Overview

Company name, sector, industry (CSRC classification)
Business description (main products/services)
Market cap, shares outstanding, float
Latest financial period (Q1/Q2/Q3/Q4, year)
Data freshness and completeness status

Part 2: Growth Profile

Revenue growth (YoY, QoQ, CAGR)
Earnings growth (YoY, QoQ, CAGR)
Growth consistency and quality
Growth drivers (organic vs. acquisition, margin expansion, etc.)
Growth outlook (consensus estimates if available)

Part 3: Profitability and Efficiency

Margin trends (gross, operating, net)
Return metrics (ROE, ROA, ROIC)
Efficiency metrics (asset turnover, inventory turnover, DSO)
Profitability vs. sector peers
Quality of earnings (cash flow vs. net income)

Part 4: Valuation Assessment

Current valuation multiples (P/E, P/B, P/S, EV/EBITDA)
Historical valuation context (percentile vs. 5-year range)
Sector relative valuation (vs. median, vs. peers)
Growth-adjusted valuation (PEG ratio)
Valuation interpretation (cheap/fair/expensive, with caveats)

Part 5: Capital Structure and Financial Health

Debt/Equity ratio and trend
Interest coverage and debt service ability
Net debt / EBITDA (leverage)
Working capital and liquidity
Financial distress signals (negative equity, covenant violations, etc.)

Part 6: Institutional and Capital Flow

Institutional ownership and recent changes
Northbound flow trends and ownership
Margin trading balance and sentiment
Dragon-tiger list activity and patterns
Share pledging risk assessment

Part 7: A-Share Specific Context

ST/*ST status and risk
Suspension history and reasons
Regulatory environment and policy sensitivity
Sector rotation and market regime effects
A-H premium/discount (if applicable)

Part 8: Data Quality and Limitations

Status of each data block (ok/partial/not_supported/stale)
Source chain and provenance
Known data gaps and missing fields
Point-in-time correctness caveats
Restatement risk and reporting lag

Step 5: Frame fundamental context honestly

When delivering results, maintain strict discipline:

Explicit status disclosure:

State which blocks are ok, partial, not_supported, or stale
List specific missing fields for partial blocks
Identify source chain for each data block
Specify data freshness (as-of date) for each block

Interpretation boundaries:

Separate reported data from derived metrics
Separate derived metrics from qualitative interpretation
Label heuristic interpretations explicitly
Do not convert partial data into strong conclusions

Fundamental analysis caveats:

"Valuation appears cheap based on P/E, but this does not account for [growth, quality, risk factors]"
"ROE is high, but leverage is also high, increasing financial risk"
"Revenue growth is strong, but cash flow is weak, suggesting quality concerns"
"Institutional ownership is increasing, but this is descriptive, not predictive"

A-share specific caveats:

"Dragon-tiger list activity suggests retail speculation, not institutional conviction"
"Northbound flow is positive, but represents only X% of float"
"Margin trading balance is high, increasing downside risk if sentiment reverses"
"Share pledging ratio is elevated, creating forced liquidation risk"

Step 6: Run the local executor

python3 <bundle-root>/fundamental-context/run.py <symbol>

Output Contract

Minimum local executor output: human-readable text beginning with 基本面上下文.
Core fields: fundamentals status, capital-flow status, dragon-tiger flag, growth metrics, earnings summary, institution changes, and sector-flow leaders when available.
Side effects: updates session memory for the current execution context.
Caller-facing delivery standard:
- Eight-part structure: Business overview, growth profile, profitability, valuation, capital structure, institutional/capital flow, A-share context, data quality
- Explicit status disclosure: State which blocks are ok/partial/not_supported/stale with specific missing fields
- Source chain transparency: Identify data source and provenance for each block
- Data freshness: Specify as-of date for each data block
- Interpretation boundaries: Separate reported data, derived metrics, and qualitative interpretation
- Fundamental analysis caveats: Explicit limitations on valuation, growth, and quality conclusions
- A-share specific caveats: Dragon-tiger interpretation, northbound flow context, margin trading risk, pledge risk
- No strong conclusions from partial data: Acknowledge incompleteness rather than overselling
- Point-in-time correctness caveats: State when data may not be strictly point-in-time correct

Failure Handling

Parse and argument errors: non-zero exit with a readable 命令错误 message.
Missing optional providers: fail open into partial or not_supported blocks instead of crashing.
Missing symbol with no reusable session symbol: readable guidance instead of a traceback.
If only one non-price block is available, acknowledge the incompleteness rather than implying a full context sweep.
Stale data: report age and recommend refresh if critical to decision.
Restatement detected: flag and explain impact on historical comparisons.
Missing critical fields: list specific gaps and impact on analysis.

Key Rules

Fundamental blocks are best-effort and fail-open by design.
Partial data is acceptable; hidden incompleteness is not.
Keep the distinction between provider output and analyst interpretation visible.
When point-in-time correctness is central to the decision, recommend a stricter data workflow instead of overselling this block.
Status disclosure is mandatory. Always state ok/partial/not_supported/stale for each block.
Source chain must be identified. State which provider/adapter supplied each block.
Data freshness must be specified. State as-of date for each block.
Valuation conclusions must be qualified. "Appears cheap" is not the same as "is cheap."
Growth metrics must include quality assessment. Revenue growth without cash flow is a red flag.
Capital flow interpretation must be cautious. Northbound buying is descriptive, not predictive.
A-share specific risks must be highlighted. Dragon-tiger, margin trading, pledging, ST status.
Do not convert partial adapter response into strong fundamental verdict.

Composition

Often complements market-analyze, decision-support, and market-brief.
Can be one component inside broader analysis or stock-data workflows.
Should be combined with technical-scan for hybrid technical-fundamental analysis.
Feeds into decision-support for position sizing based on fundamental quality.
Used by analysis skill to support thesis with fundamental evidence.