detect-atr-squeeze-regime

<essential_principles>

Traditional ATR is an absolute value (in price units), so assets at different price levels cannot be compared. After converting ATR to a percentage (ATR / Close * 100):

Volatility strength can be compared across assets
A "normal baseline" (3-year moving average) can be established
A "multiplier" can be used to determine whether it has entered an abnormal volatility zone

ATR% = (14-day EMA of True Range) / Close * 100
Ratio = Current ATR% / 3-year Rolling Mean ATR%

Market	ATR% condition	Ratio condition	Market characteristics
`orderly_market`	Normal range	< 1.2	Technical levels are effective, stop losses are precise, trend following is reliable
`elevated_volatility_trend`	Elevated	1.2 - 2.0	Technical levels are less effective, stop losses need to be widened, directionality remains
`volatility_dominated_squeeze`	>= high volatility threshold	>= 2.0	Technical levels fail, stop losses are frequently swept, reflexivity dominates

Squeeze marketdetermination requiressimultaneouslysatisfying:

ATR% >= high_vol_threshold_pct(default 6%)
Ratio >= spike_threshold_x(default 2.0)

When entering volatility_dominated_squeeze market:

Price movement is dominated by "forced flows"：

Margin adjustments / leverage deleveraging
Options Delta/Gamma hedging
Short covering
Passive risk parity rebalancing

Technical level reliability declines：

Breakouts/breakdowns are more often the result of liquidity and risk-control triggers
They do not represent a change in fundamentals or trend confirmation

Stop-loss fragility：

A single volatility move can sweep through multiple layers of stops
Low-timeframe conviction trading is "structurally impaired"
Even if the macro view is right, it is hard to sustain: short-term noise is large enough to wash out positions with the correct direction first

When a squeeze market is detected:

Adjustment item	Orderly market	Squeeze market
Stop-loss multiplier	1.0-1.5 ATR	2.0-3.0 ATR
Position scaling	Normal	Reduce to 1/ATR%
Time frame	Intraday/short-term	Switch to a longer period
Instrument selection	Naked positions	Options/spread structures
Trust in technical levels	High	Low (regarded as noise)

</essential_principles>

Calculate ATR%: the 14-day EMA-smoothed true range percentage
Establish baseline: the 3-year rolling mean as the "normal" reference
Determine market regime: compare the current value with the baseline multiplier
Output recommendations: stop-loss adjustment, position scaling, trust in technical levels

Output: market regime determination, ATR% value, multiplier, actionable risk-control recommendations.

<quick_start>

Fastest way: detect silver (SI=F)

cd skills/detect-atr-squeeze-regime
pip install pandas numpy yfinance pandas_ta  # 首次使用
python scripts/atr_squeeze.py --symbol SI=F --quick

Output example:

{
  "symbol": "SI=F",
  "as_of": "2026-01-14",
  "regime": "volatility_dominated_squeeze",
  "atr_pct": 7.23,
  "atr_ratio_to_baseline": 2.41,
  "tech_level_reliability": "low",
  "tech_level_reliability_score": 28,
  "suggested_stop_atr_mult": 2.5,
  "position_scale": 0.41
}

Full analysis：

python scripts/atr_squeeze.py --symbol XAGUSD --start 2020-01-01 --end 2026-01-01 --output result.json

Generate visualization dashboard：

pip install matplotlib  # 首次使用
python scripts/plot_atr_squeeze.py --symbol SI=F --output output/

The dashboard includes:

Price trend chart
ATR% volatility time series
ATR multiplier dashboard
Current status and risk-control recommendation panel

</quick_start>

Quick detection - Check the current market regime of a single asset
Multi-Asset Scan - Scan multiple assets for squeeze conditions
Historical Backtest - Retrospectively identify past squeeze periods
Continuous Monitoring - Set up alerts to notify when the regime switches
Methodology Learning - Understand the theoretical basis of ATR squeeze conditions

Please select or directly provide an asset symbol to begin analysis.

After routing, read the corresponding document and execute.

<directory_structure>

detect-atr-squeeze-regime/
├── SKILL.md                           # 本文件（路由器）
├── skill.yaml                         # 前端展示元數據
├── manifest.json                      # 技能元數據
├── workflows/
│   ├── detect.md                      # 單資產偵測工作流
│   ├── monitor.md                     # 多資產監控工作流
│   └── backtest.md                    # 歷史回測工作流
├── references/
│   ├── methodology.md                 # ATR 擠壓行情方法論
│   ├── input-schema.md                # 完整輸入參數定義
│   └── data-sources.md                # 資料來源說明
├── templates/
│   ├── output-json.md                 # JSON 輸出模板
│   └── output-markdown.md             # Markdown 報告模板
├── scripts/
│   ├── atr_squeeze.py                 # 主偵測腳本
│   └── plot_atr_squeeze.py            # 視覺化儀表盤腳本
└── examples/
    └── xagusd-squeeze-2024.json       # 範例輸出

</directory_structure>

<reference_index>

Methodology: references/methodology.md

ATR% Normalization Principles
Three-Regime Classification Logic
Interpretation of Reflexivity Mechanisms
Ole Hansen Silver Squeeze Case

Data Sources: references/data-sources.md

Yahoo Finance Futures Symbols
Stooq Alternative Source
Data Frequency and Alignment

Input Parameters: references/input-schema.md

Complete Parameter Definitions
Default Values and Recommended Ranges

</reference_index>

<workflows_index>

Workflow	Purpose	When to Use
detect.md	Single-Asset Detection	Need to check a specific asset
monitor.md	Multi-Asset Monitoring	Daily scanning or alerts
backtest.md	Historical Backtest	Validate detection accuracy
</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
atr_squeeze.py	`--symbol SI=F --quick`	Quickly check current status
atr_squeeze.py	`--symbol SI=F --start DATE`	Complete historical analysis
atr_squeeze.py	`--scan SI=F,GC=F,CL=F`	Multi-asset scan
plot_atr_squeeze.py	`--symbol SI=F --output output/`	Generate a visualization dashboard
</scripts_index>

<input_schema_summary>

Core Parameters

Parameter	Type	Default Value	Description
symbol	string	(required)	Asset Symbol
start_date	string	today-5y	Sampling Start Date
end_date	string	today	Sampling End Date
timeframe	string	1d	Price Frequency

ATR Parameters

Parameter	Type	Default Value	Description
atr_period	int	14	ATR Period
atr_smoothing	string	ema	Smoothing Method (ema/wilder)
use_percent_atr	bool	true	Whether to Convert to Percentage

Regime Determination Parameters

Parameter	Type	Default Value	Description
baseline_window_days	int	756	Long-Term Baseline Window (about 3 years)
spike_threshold_x	number	2.0	Multiplier Threshold
high_vol_threshold_pct	number	6.0	Absolute ATR% High Volatility Threshold

For complete parameter definitions, see references/input-schema.md。

</input_schema_summary>

<output_schema_summary>

{
  "skill": "detect-atr-squeeze-regime",
  "symbol": "SI=F",
  "as_of": "2026-01-14",
  "regime": "volatility_dominated_squeeze",
  "atr_pct": 7.23,
  "atr_ratio_to_baseline": 2.41,
  "baseline_atr_pct": 3.0,
  "tech_level_reliability": "low",
  "tech_level_reliability_score": 28,
  "risk_adjustments": {
    "suggested_stop_atr_mult": 2.5,
    "position_scale": 0.41,
    "recommended_timeframe": "weekly",
    "instrument_suggestion": "options_or_spreads"
  },
  "interpretation": {
    "regime_explanation": "...",
    "tactics": ["...", "..."]
  }
}

For the complete output structure, see templates/output-json.md。 </output_schema_summary>

<success_criteria> On successful execution, it should produce:

Current regime determination (orderly / elevated / squeeze)
ATR% value and its multiplier relative to the baseline
Technical level reliability score (0-100)
Recommended stop-loss multiplier
Recommended position scaling factor
Regime interpretation and tactical recommendations
Time series data (optional, for visualization)
Visualization dashboard PNG (optional, use plot_atr_squeeze.py) </success_criteria>

About this skill