<essential_principles>
Core Principles of Asset Trend Deviation Analysis
<principle name="exponential_trend_fitting">
**Exponential Trend Line Fitting**
Most assets follow an exponential growth path over long-term (decades-long) scales. Fit the trend line via logarithmic price linear regression (y = a + b*t where y = log(price)), trend = exp(a + b*t). Deviation = (price / trend - 1) × 100%.
</principle>
<principle name="historical_context">
**Historical Extreme Comparison**
Provide context for the market position by calculating the quantile of the current deviation in the historical distribution, as well as comparing it with historical peaks/troughs. Users can specify a specific date as a reference point, or the system can automatically identify historical extreme values.
</principle>
<principle name="regime_classification">
**Market Regime Assessment (Optional)**
For specific assets (such as gold, stock indices), macro factor analysis can be integrated to assess market regimes. Different assets have different regime classification frameworks, and users can customize assessment rules and factor weights.
</principle>
<principle name="universal_applicability">
**Universal Applicability**
This skill is applicable to any asset with long-term exponential growth characteristics: commodities (gold, crude oil), stock indices, cryptocurrencies, real estate, etc. The core logic does not presuppose specific assets or historical peaks.
</principle>
</essential_principles>
<intake>
**What operation would you like to perform?**
- Single Asset Detection - Calculate the trend deviation and historical quantile of a single asset
- Historical Comparison Analysis - Compare the current deviation with a user-specified historical date or automatically identified extreme values
- Macro Factor Decomposition - Detailed breakdown of the contribution of each macro proxy indicator to market regime assessment (applicable to supported asset classes)
Please respond to continue.
</intake>
<routing>
| Response | Workflow | Description |
|------------------------------------|-----------------------|-------------|
| 1, "detect", "single", "偵測" | workflows/detect.md | Single asset trend deviation detection and regime assessment |
| 2, "compare", "historical", "對照" | workflows/compare.md | Detailed historical peak comparison analysis |
| 3, "macro", "breakdown", "因子" | workflows/macro.md | Macro factor decomposition and contribution analysis |
After reading the workflow, please follow its steps exactly.
</routing>
<quick_start>
Quick Start
bash
# Install dependencies
pip install pandas numpy yfinance pandas-datareader statsmodels
# Quick Detection (Example: Gold Futures)
cd skills/evaluate-exponential-trend-deviation-regimes
python scripts/trend_deviation.py --symbol GC=F --quick
# Analyze Other Assets (Example: S&P 500)
python scripts/trend_deviation.py --symbol ^GSPC --start 1950-01-01
# Full Analysis (Including Macro Factors, Currently Supports Gold)
python scripts/trend_deviation.py --symbol GC=F --start 1970-01-01 --include-macro
# Specify Historical Reference Date
python scripts/trend_deviation.py --symbol GC=F --compare-peaks "2011-09-06,2020-08-07"
# Generate Visualization Charts (Output PNG + JSON)
python scripts/generate_chart.py --output ./output/
</quick_start>
<reference_index>
Reference Documents (
)
| Document | Content |
|---|
| input-schema.md | Detailed definition and validation rules for input parameters |
| methodology.md | Methodology for exponential trend fitting and deviation calculation |
| regime-rules.md | Regime assessment rules for 1970s-like vs 2000s-like |
| data-sources.md | Data sources and alternative solutions description |
| </reference_index> | |
<workflows_index>
| Workflow | Purpose |
|---|
| detect.md | Single asset trend deviation detection and regime assessment |
| compare.md | Detailed historical peak comparison analysis |
| macro.md | Macro factor decomposition and contribution analysis |
| </workflows_index> | |
<templates_index>
| Template | Purpose |
|---|
| output-json.md | JSON output structure definition |
| output-markdown.md | Markdown report output template |
| </templates_index> | |
<scripts_index>
| Script | Purpose |
|---|
| trend_deviation.py | Main analysis script: trend fitting, deviation calculation, regime assessment |
| generate_chart.py | Visualization chart generation: historical deviation chart and peak annotation |
| </scripts_index> | |
<examples_index>
Example Outputs (
)
| Document | Content |
|---|
| gold-deviation-2026.json | Example of gold trend deviation analysis in 2026 |
| </examples_index> | |
<success_criteria>
When the skill is successfully executed: