<essential_principles>
<principle name="narrative_verification">
**Narrative Verification Instead of Prediction**
This skill focuses on "verifying narratives with data":
- Input: Communities/news claim that "natural gas price surge leads to abnormal fertilizer supply/price"
- Output: Causal hypothesis test results on time series
No price prediction is made; only answers: "Is this narrative supported by data?"
</principle>
<principle name="three_part_test">
**Three-Stage Causal Test**
For the narrative to hold, all three-stage conditions must be satisfied simultaneously:
| Stage | Condition | Testing Method |
|---|
| Stage A | Natural gas enters shock regime | z-score or slope threshold breakthrough |
| Stage B | Fertilizer shows spike after Stage A | Test with the same method, and the starting point is later than that of natural gas |
| Stage C | Lead-lag relationship supports causality | cross-correlation shows gas leads fert |
If A→B→C holds, the narrative has quantitative support; otherwise, alternative explanations are provided.
</principle>
<principle name="regime_detection">
**Regime Detection Logic**
Use rolling z-score + slope dual confirmation:
python
# z-score detection
z_t = (r_t - rolling_mean(r, window)) / rolling_std(r, window)
shock = z_t >= threshold_z # Default 3.0
# Slope detection (supplementary)
slope_t = (price_t / price_{t-k} - 1) / k
shock |= slope_t >= threshold_slope # Default 1.5%/day
Consecutive shock days are merged into regimes, with start/end/peak values output.
</principle>
<principle name="lead_lag_interpretation">
**Lead-Lag Interpretation**
Interpretation of cross-correlation results:
| lag Value | Meaning | Narrative Support Level |
|---|
| lag > 0 | Natural gas leads fertilizer | High (meets expectations) |
| lag ≈ 0 | Simultaneous changes | Medium (common driving factor) |
| lag < 0 | Fertilizer leads natural gas | Low (weak narrative) |
Reasonable lead period: 1-8 weeks (7-56 days)
</principle>
<principle name="data_source_priority">
**Data Source Priority**
Primary: TradingEconomics (crawled via fully automated Chrome CDP)
Backup: FRED Henry Hub + World Bank Pink Sheet
Fully Automated Chrome CDP Crawling:
The script automatically completes the following steps without manual operation:
- Automatically start Chrome debug mode
- Open TradingEconomics page and wait for chart loading
- Execute JavaScript via WebSocket connection to extract Highcharts data
- Automatically navigate to multiple commodity pages (e.g., natural gas → fertilizer)
- Automatically close Chrome after completion
Completely bypasses Cloudflare, no manual verification required.
</principle>
</essential_principles>
<objective>
Verify the causal hypothesis of "natural gas price surge → fertilizer price surge".
Output three levels of analysis:
- Shock Regimes: Parabolic/surge intervals of natural gas and fertilizer
- Lead-Lag Test: Lead-lag correlation analysis
- Narrative Assessment: Narrative credibility judgment
</objective>
<quick_start>
Fully Automated Mode: One-click completion of data crawling, analysis and visualization
The script will automatically start Chrome, crawl data, close Chrome, no manual operation required.
Step 1: Install Dependencies
bash
pip install requests websocket-client pandas numpy matplotlib scipy
Step 2: Fully Automated Data Crawling (automatically start/close Chrome)
bash
cd scripts
python fetch_te_data.py --symbol natural-gas --symbol urea
Step 3: Execute Causal Hypothesis Analysis
bash
python gas_fertilizer_analyzer.py \
--gas-file ../data/cache/natural-gas.csv \
--fert-file ../data/cache/urea.csv \
--output ../data/analysis_result.json
Step 4: Generate Visualization Charts (Bloomberg style)
bash
python visualize_shock_regimes.py
# Automatically output to: output/gas_fert_shock_YYYY-MM-DD.png
Sample Output:
json
{
"signal": "narrative_supported",
"confidence": "medium",
"gas_shock_regimes": [
{"start": "2026-01-20", "peak": "2026-01-22", "regime_return_pct": 29.1}
],
"fert_spike_regimes": [
{"start": "2025-10-27", "peak": "2025-10-27", "regime_return_pct": 0.0}
],
"lead_lag_test": {
"best_lag_days_gas_leads_fert": 21,
"best_corr": 0.131
},
"interpretation": "Natural gas leads fertilizer by about 21 days, the narrative has quantitative support"
}
Note: When executing for the first time, Chrome will automatically start and crawl data in the background (about 60 seconds), and close automatically after completion.
</quick_start>
<intake>
What analysis do you need?
- Quick Check - Check if there has been a recent natural gas shock and fertilizer follow-up
- Full Analysis - Execute the three-stage causal test and generate a report
- Contract Hedge Hypothesis - Input contract prices and calculate spread pressure indicators
- Methodology Learning - Understand the principles of shock detection and lead-lag analysis
Please select or directly provide analysis parameters.
</intake>
<routing>
| Response | Action |
|--------------------------------|--------------------------------------------|
| 1, "quick", "check" | Read `workflows/quick-check.md` and execute |
| 2, "full", "analyze" | Read `workflows/analyze.md` and execute |
| 3, "contract", "hedge" | Read `workflows/hedge-hypothesis.md` and execute|
| 4, "learn", "methodology", "why" | Read `references/methodology.md` |
| Provide parameters (e.g., dates/commodities) | Read `workflows/analyze.md` and execute with parameters |
After routing, read the corresponding file and execute.
</routing>
<directory_structure>
analyze-gas-fertilizer-contract-shock/
├── SKILL.md # This file (router)
├── skill.yaml # Frontend display metadata
├── manifest.json # Skill metadata
├── workflows/
│ ├── analyze.md # Full three-stage analysis workflow
│ ├── quick-check.md # Quick check workflow
│ └── hedge-hypothesis.md # Contract hedge hypothesis analysis
├── references/
│ ├── data-sources.md # Chrome CDP crawler description
│ ├── methodology.md # Shock detection and lead-lag methodology
│ ├── input-schema.md # Input parameter definitions
│ └── historical-episodes.md # Historical case comparisons
├── templates/
│ ├── output-json.md # JSON output template
│ └── output-markdown.md # Markdown report template
├── scripts/
│ ├── fetch_te_data.py # TradingEconomics CDP crawler
│ ├── gas_fertilizer_analyzer.py # Main analysis script
│ └── visualize_shock_regimes.py # Shock regime visualization
├── data/ # Data cache directory
│ └── cache/ # Cache files
└── examples/
└── sample_output.json # Sample output
</directory_structure>
<reference_index>
Methodology: references/methodology.md
- Shock/Spike detection logic (z-score + slope)
- Lead-lag correlation analysis
- Regime merging algorithm
Data Sources: references/data-sources.md
- TradingEconomics Chrome CDP crawler description
- Natural gas and fertilizer commodity codes
- Backup data sources (FRED/World Bank)
Input Parameters: references/input-schema.md
- Complete parameter definitions and default values
- te_symbols, spike_detection, lead_lag, etc.
Historical Cases: references/historical-episodes.md
- 2021-2022 European natural gas crisis
- 2022 Russia-Ukraine conflict period
- Seasonal fluctuation cases
</reference_index>
<workflows_index>
| Workflow | Purpose | Application Scenario |
|---|
| analyze.md | Full three-stage causal analysis | When narrative verification is needed |
| quick-check.md | Quick check of recent shocks | Daily monitoring or quick response |
| hedge-hypothesis.md | Contract hedge hypothesis analysis | Calculate spread pressure indicators given contract prices |
| </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 |
|---|
| fetch_te_data.py | --symbol natural-gas --symbol urea
| Fully automated CDP crawling (auto start/close Chrome) |
| gas_fertilizer_analyzer.py | --gas-file X.csv --fert-file Y.csv
| Full three-stage causal analysis |
| visualize_shock_regimes.py | (No parameters, automatically reads cache) | Bloomberg-style visualization charts |
| </scripts_index> | | |
<input_schema>
<parameter name="start_date" required="true">
**Type**: string (ISO YYYY-MM-DD)
**Description**: Analysis start date
**Example**: "2025-08-01"
</parameter>
<parameter name="end_date" required="true">
**Type**: string (ISO YYYY-MM-DD)
**Description**: Analysis end date
**Example**: "2026-02-01"
</parameter>
<parameter name="te_symbols" required="true">
**Type**: object
**Description**: TradingEconomics commodity codes
```json
{
"natural_gas": "natural-gas", // Or "Natural Gas"
"fertilizer": "urea" // Or "dap", "fertilizer"
}
```
</parameter>
<parameter name="spike_detection" required="false">
**Type**: object
**Defaults**:
```json
{
"return_window": 1,
"z_window": 60,
"parabolic_threshold": {"z": 3.0, "slope_pct_per_day": 1.5}
}
```
</parameter>
<parameter name="lead_lag" required="false">
**Type**: object
**Defaults**:
```json
{
"max_lag_days": 60,
"method": "corr_returns"
}
```
</parameter>
</input_schema>
<output_schema>
See the complete structure definition in
.
Summary:
json
{
"signal": "narrative_supported | narrative_weak | inconclusive",
"confidence": "high | medium | low",
"gas_shock_regimes": [...],
"fert_spike_regimes": [...],
"lead_lag_test": {
"best_lag_days": 12,
"best_corr": 0.41,
"interpretation": "gas leads fert"
},
"narrative_assessment": "Summary of three-stage test results",
"artifacts": {
"charts": ["output/gas_fert_shock.png"]
}
}
</output_schema>
<success_criteria>
When the analysis is successful, it should produce: