backsolve-miner-vs-metal-ratio-with-fundamentals

<essential_principles>

The mining stock/metal price ratio can be decomposed into four fundamental factors:

R_t ≈ K × M_t × (1-L_t) × C_t × D_t

Where:

K: Calibration constant (estimated from observed values)
M_t: Multiple factor (EV/EBITDA)
(1-L_t): Leverage factor (1 - NetDebt/EV)
C_t: Cost factor (1 - AISC/S_t)
D_t: Dilution factor (Shares_base / Shares_t)

This decomposition gives "ratio changes" an attributable quantitative explanation.

All-in sustaining cost (AISC) is the core driver of mining stock valuation:

Priority	Source	Method
1	MD&A / financial statement notes	Keyword extraction: "AISC" "all-in sustaining"
2	Annual report presentation PDF	Parse tables: $/oz or $/ounce
3	Proxy back-calculation	(OpCost + SustCapex + G&A - Byproduct) / Oz

When direct disclosure is unavailable, use proxy back-calculation to fill gaps; record aisc_method to annotate the source.

Goal: Given a target ratio R* (e.g., historical top of 1.7), back-solve for which factor conditions are required.

Single-factor back-solve: Assume other factors remain unchanged, adjust only a single factor

M* = M_now × (R*/R_now)         # 需要的倍數
(1-L*) = (1-L_now) × (R*/R_now) # 需要的去槓桿
C* = C_now × (R*/R_now)         # 需要的成本改善 → 反推 AISC*
D* = D_now × (R*/R_now)         # 需要的稀釋折扣

Two-factor combination: Enumerate feasible combinations with a grid (e.g., multiple +20% + silver -15%).

Identify historical events where "the ratio fell into the bottom quantile," and look back at the four factor states during the event period:

Whether AISC rose: Cost pressure
Whether NetDebt/EV deteriorated: Leverage pressure
Whether EV/EBITDA compressed: Multiple pressure
Whether Shares rose: Dilution pressure

Rank "which factor contributed the most" to identify the main driver of the bottom.

Follow the "structured-first" principle:

SEC XBRL (10-K/10-Q): Directly take fields (debt, cash, share count, CFO, Capex)
SEDAR+ (Canada): Silver mining companies are often listed in Canada
Company IR annual report/MD&A: Fill in non-standard fields such as AISC and production
ETF Holdings: Official CSV or SEC N-PORT

When scraping, use Selenium to simulate human behavior to avoid being blocked.

</essential_principles>

Data integration: Scrape prices, ETF holdings, financial statements, operational disclosures
Factor calculation: Calculate the four major factors: AISC, leverage, multiple, dilution
Ratio decomposition: Establish the approximation R_t ≈ K × M × (1-L) × C × D
Threshold back-solve: Given a target ratio, back-solve for the required factor combination
Event study: Factor-driven analysis of historical bottom events
Output report: Structured JSON and readable Markdown

Target user: When seeing an extreme SIL/silver ratio, wants to use "real financial statements" to verify the drivers.

<quick_start>

Fastest way: Analyze using default parameters

cd skills/backsolve-miner-vs-metal-ratio-with-fundamentals
pip install pandas numpy yfinance matplotlib  # 首次使用
python scripts/fundamental_analyzer.py --quick

Full analysis (including financial statement scraping)

python scripts/fundamental_analyzer.py \
  --metal-symbol SI=F \
  --miner-universe etf:SIL \
  --region-profile us_sec \
  --start-date 2015-01-01 \
  --output result.json

Generate a visualization dashboard

python scripts/visualize_factors.py --quick --output output/
# 輸出: output/sil_silver_factor_analysis_YYYY-MM-DD.png

The visualization dashboard contains four panels:

Ratio time series: historical trend + quantile bands (bottom/top)
Factor radar chart: overview of the health of the four major factors
Factor score bar chart: scores for cost, leverage, multiple, and dilution
Scenario heatmap: combined analysis of multiple expansion × silver price change

Joint rally scenario simulation

python scripts/scenario_path_simulator.py --quick --output output/
# 輸出: output/scenario_path_YYYY-MM-DD.png + return_heatmap_YYYY-MM-DD.png

Core formula:Mining stock gain = (1 + silver price gain) × (R₁/R₀) - 1

Custom parameters:

python scripts/scenario_path_simulator.py \
  --silver-monthly 5 \      # 銀價每月漲幅 5%
  --ratio-start 1.10 \      # 比率起點
  --ratio-end 1.20 \        # 比率終點
  --months 6 \              # 模擬 6 個月
  --heatmap                 # 同時生成熱力圖

Output example：

{
  "now": {
    "metal_price": 94.4,
    "miner_price": 103.4,
    "ratio": 1.13,
    "ratio_percentile": 0.111
  },
  "thresholds": {
    "bottom_ratio": 1.20,
    "top_ratio": 1.70,
    "median_ratio": 1.51
  },
  "fundamentals_weighted": {
    "aisc_usd_per_oz": 28.0,
    "net_debt_to_ev": 0.25,
    "ev_to_ebitda": 6.4,
    "shares_yoy_change": 0.12
  },
  "factors_now": {
    "cost_factor_C": 0.7034,
    "leverage_factor_1_minus_L": 0.75,
    "multiple_M": 6.4,
    "dilution_discount_D": 0.89
  },
  "backsolve_to_top": {
    "multiple_only_need": 9.1,
    "deleverage_only_need_1_minus_L": 1.12,
    "cost_only_implied_aisc": 15.6,
    "dilution_only_need_D": 1.26
  }
}

</quick_start>

Quick analysis - calculate the current factor state using default parameters (SIL / SI=F)
Full analysis - fetch financial statements, calculate factors, infer thresholds
Factor breakdown - gain a deeper understanding of the calculation logic of the four major factors
Threshold inference - given a target ratio, calculate the required factor combination
Event study - factor-driven ranking of historical bottom events
Methodology learning - understand the back-calculation logic and data sources
Visualization - generate a four-panel dashboard chart
Joint rally scenario - simulate the proportional relationship and path when silver prices and mining stocks rise together

Please select or directly provide analysis parameters.

After routing, read the corresponding document and execute.

<directory_structure>

backsolve-miner-vs-metal-ratio-with-fundamentals/
├── SKILL.md                           # 本文件（路由器）
├── skill.yaml                         # 前端展示元數據
├── manifest.json                      # 技能元數據
├── workflows/
│   ├── analyze.md                     # 完整分析工作流
│   └── data-fetch.md                  # 數據抓取工作流
├── references/
│   ├── input-schema.md                # 完整輸入參數定義
│   ├── data-sources.md                # 數據來源說明
│   ├── fundamental-factors.md         # 四大因子計算邏輯
│   └── backsolve-math.md              # 反推數學公式
├── templates/
│   ├── output-json.md                 # JSON 輸出模板
│   └── output-markdown.md             # Markdown 報告模板
├── scripts/
│   ├── fundamental_analyzer.py        # 主計算腳本
│   ├── visualize_factors.py           # 視覺化儀表板腳本
│   └── scenario_path_simulator.py     # 共同上漲情境模擬器
└── examples/
    └── sample-output.json             # 範例輸出

</directory_structure>

<reference_index>

Input parameters: references/input-schema.md

Full parameter definitions
Default values and recommended ranges
Description of each method option

Data sources: references/data-sources.md

Price data (yfinance / stooq / alphavantage)
Financial statement data (SEC EDGAR / SEDAR+ / company IR)
ETF holdings (official CSV / N-PORT / manual URL)

Factor calculations: references/fundamental-factors.md

AISC cost factor
Leverage factor
Multiple factor
Dilution factor

Inference mathematics: references/backsolve-math.md

Single-factor inference formula
Two-factor combination grid
Calibration constant estimation

</reference_index>

<workflows_index>

Workflow	Purpose	When to use
analyze.md	Full analysis	Needs to fetch financial statements and calculate factors
data-fetch.md	Data fetching	Learn how to fetch ETF holdings and financial statements
</workflows_index>

<templates_index>

Template	Purpose
output-json.md	JSON output structure definition
output-markdown.md	Markdown report template
</templates_index>

<scripts_index>

Script	Command	Purpose
fundamental_analyzer.py	`--quick`	Quick analysis SIL/SI=F
fundamental_analyzer.py	`--miner-universe etf:SILJ`	Custom mining stock ETF
fundamental_analyzer.py	`--backsolve-target 1.7`	Specify target ratio for inference
fundamental_analyzer.py	`--event-study --min-separation 180`	Run event study
visualize_factors.py	`--quick --output output/`	Generate four-panel visualization dashboard
visualize_factors.py	`--input result.json`	Generate charts from JSON results
scenario_path_simulator.py	`--quick`	Joint rally scenario path simulation
scenario_path_simulator.py	`--silver-monthly 5 --months 6`	Customize silver price monthly gain and number of simulation months
scenario_path_simulator.py	`--ratio-start 1.10 --ratio-end 1.20`	Customize ratio start and end points
scenario_path_simulator.py	`--heatmap`	Also generate a return heatmap
</scripts_index>

<input_schema_summary>

Core parameters

Parameter	Type	Default value	Description
metal_symbol	string	SI=F	Metal price ticker (SI=F silver, GC=F gold)
miner_universe	object	etf:SIL	Mining stock/ETF definition
region_profile	string	us_sec	Regulatory and disclosure sources (us_sec / canada_sedar)
time_range.start	string	5 years ago	Analysis start date (YYYY-MM-DD)
time_range.end	string	today	Analysis end date
time_range.frequency	string	weekly	Sampling frequency (daily/weekly/monthly)

Factor method selection

Parameter	Type	Default value	Description
fundamental_methods.aisc	string	hybrid	AISC extraction method
fundamental_methods.leverage	string	net_debt_to_ev	Leverage calculation method
fundamental_methods.multiple	string	ev_to_ebitda	Multiple calculation method
fundamental_methods.dilution	string	weighted_avg_shares	Dilution calculation method

Quantile thresholds

Parameter	Type	Default value	Description
ratio_thresholds.bottom	float	0.20	Bottom quantile threshold
ratio_thresholds.top	float	0.80	Top quantile threshold

Full parameter definitions see references/input-schema.md。

</input_schema_summary>

<output_schema_summary>

{
  "skill": "backsolve_miner_vs_metal_ratio_with_fundamentals",
  "inputs": {
    "metal_symbol": "SI=F",
    "miner_universe": {"type": "etf_holdings", "etf_ticker": "SIL"},
    "region_profile": "us_sec"
  },
  "now": {
    "metal_price": 94.4,
    "miner_price": 103.4,
    "ratio": 1.13,
    "ratio_percentile": 0.111
  },
  "thresholds": {
    "bottom_ratio": 1.20,
    "top_ratio": 1.70,
    "median_ratio": 1.51
  },
  "fundamentals_weighted": {
    "aisc_usd_per_oz": 28.0,
    "net_debt_to_ev": 0.25,
    "ev_to_ebitda": 6.4,
    "shares_yoy_change": 0.12
  },
  "factors_now": {
    "cost_factor_C": 0.7034,
    "leverage_factor_1_minus_L": 0.75,
    "multiple_M": 6.4,
    "dilution_discount_D": 0.89
  },
  "backsolve_to_top": {
    "multiple_only_need": 9.1,
    "deleverage_only_need_1_minus_L": 1.12,
    "cost_only_implied_aisc": 15.6,
    "dilution_only_need_D": 1.26,
    "two_factor_grid_examples": [
      {"multiple_up": 1.20, "metal_down": -0.15, "hits_top": true},
      {"deleverage": -0.10, "multiple_up": 1.15, "hits_top": true}
    ]
  },
  "event_study": {
    "bottom_events": [
      {
        "date": "2026-01-02",
        "ratio": 1.13,
        "aisc": 29.1,
        "net_debt_to_ev": 0.27,
        "ev_to_ebitda": 5.8,
        "shares_yoy": 0.14,
        "dominant_driver": "multiple_compression"
      }
    ]
  },
  "summary": "比率處於歷史底部，主要驅動為倍數壓縮...",
  "notes": [
    "AISC 使用 hybrid 方法回算，部分公司為 proxy 值",
    "建議交叉驗證：COT 持倉、ETF 流量、美元/實質利率"
  ]
}

Full output structure see templates/output-json.md。 </output_schema_summary>

<success_criteria> On successful execution, should produce:

Current ratio and historical quantiles
Four fundamental factors (AISC, leverage, multiple, dilution)
Combined factor after weight aggregation
Threshold reverse-derivation results (single-factor + two-factor combinations)
Factor driver ranking of historical bottom events
Results output in the specified format (JSON or Markdown)
Data sources and method annotations (aisc_method, etc.)
Risk warnings and follow-up research suggestions
Visualization dashboard (PNG format, filename includes date) </success_criteria>

About this skill