# Regime Overlay

> Use when adding a regime filter to any directional strategy on Superior Trade — anything described as regime gate, trend filter, directional confirmation, ADX gate, EMA-separation filter, trade-or-skip overlay. Provides three reusable building blocks (regime_strong_bear, regime_strong_bull, regime_range) that wrap entry signals with triple-confirmation (EMA separation + ADX + N-bar return). Valid…

- **Type:** Skill
- **Install:** `agentstack add skill-superior-trade-superior-skills-regime-overlay`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Superior-Trade](https://agentstack.voostack.com/s/superior-trade)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Superior-Trade](https://github.com/Superior-Trade)
- **Source:** https://github.com/Superior-Trade/superior-skills/tree/main/skills/regime-overlay

## Install

```sh
agentstack add skill-superior-trade-superior-skills-regime-overlay
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Regime Overlay — Triple-Confirmation Gate

A reusable filter that wraps any directional strategy and only allows entries when three independent regime confirmations align. Validated as the difference between a fragile and a robust trend strategy.

Searchable under: **regime filter**, **trend gate**, **trade-or-skip filter**, **directional confirmation**, **ADX gate**.

## Why a separate primitive

After 21 backtests, the single biggest performance lever was not entry logic, stop sizing, or trailing config. It was **whether the strategy traded at all** during specific market structure.

The proof:
- Same Donchian-breakdown short on BTC 4h, no regime gate → **+12.85%** over 162d (looks great)
- Same strategy, on a different window (the rangy second half) → **-4.32%** (edge gone)
- Same strategy with triple-confirmed regime gate → **+6.69% with 0% drawdown**, fires zero trades in the chop window

The first version captured a real edge mixed with random noise. The third version captured **only** the real edge. Smaller absolute return; cleaner equity curve; no losing periods.

## The three confirmations

A signal is "in regime" when ALL three of these hold simultaneously:

| Indicator | Threshold | What it confirms |
|---|---|---|
| `(EMA50 - EMA200) / EMA200` |  25 | **Strength** of the current trend |
| `close.pct_change(30)` |  +0.06`
- `ADX(14) > 25` (same — ADX is direction-agnostic)
- `close.pct_change(30) > +0.10`

## Implementation

```python
def regime_strong_bear(df: pd.DataFrame) -> pd.Series:
    ema50 = ta.EMA(df, timeperiod=50)
    ema200 = ta.EMA(df, timeperiod=200)
    adx = ta.ADX(df, timeperiod=14)
    ema_sep = (ema50 - ema200) / ema200
    ret_30 = df["close"].pct_change(30)
    return (ema_sep  25) & (ret_30  pd.Series:
    ema50 = ta.EMA(df, timeperiod=50)
    ema200 = ta.EMA(df, timeperiod=200)
    adx = ta.ADX(df, timeperiod=14)
    ema_sep = (ema50 - ema200) / ema200
    ret_30 = df["close"].pct_change(30)
    return (ema_sep > 0.06) & (adx > 25) & (ret_30 > 0.10)

def regime_range(df: pd.DataFrame) -> pd.Series:
    adx = ta.ADX(df, timeperiod=14)
    return adx < 25
```

The range-regime check is the opposite end of the spectrum — useful for gating mean-reversion strategies (see `bollinger-reverter-4h`).

## Expected behavior

Apply this overlay to any signal-driven entry. The cost is **fewer trades**; the benefit is **the trades you do take fire in the right environment.**

| Strategy | Without overlay | With overlay |
|---|---|---|
| Donchian breakdown BTC | 23 trades, 56.5% win, +12.85%, 3.69% DD | **6 trades, 100% win, +6.69%, 0% DD** |
| (Same, second-half only) | 8 trades, 25% win, -4.32% | **0 trades, no PnL** |

The overlay traded the second column's win rate **and drawdown** for the first column's absolute return. Most production strategies should prefer the second column.

## Tunables

| Parameter | Conservative | Aggressive | Notes |
|---|---|---|---|
| EMA separation threshold | 0.08 | 0.04 | Tighter = wait for deeper structural moves |
| ADX threshold | 30 | 20 | Higher = stricter trend-strength requirement |
| Return lookback bars | 40 | 20 | Window for "actual momentum" check |
| Return threshold | 0.15 | 0.06 | How much momentum needed |

Start conservative (0.06 / 25 / -0.10). Loosen only if the gate eliminates so many trades that the strategy's edge can't compound.

## What this is NOT

- Not a signal in itself. The overlay only says "regime is right"; it doesn't tell you when to enter
- Not magic. In an environment where the historical regime gate would never fire (e.g., a yearlong sideways grind), the strategy simply stays out. That's the feature
- Not a replacement for stops or take-profit. Even regime-confirmed signals fail individually

## When NOT to use a regime gate

- Mean-reversion strategies (`bollinger-reverter-4h`) work IN range regimes — use `regime_range` (ADX < 25) instead of bear/bull strong gates
- Funding-carry strategies that earn rebates rather than directional moves
- Pair-arbitrage or basis-arb strategies where the edge is structural, not regime-conditional

## Pairing patterns

Most directional strategies in this repo benefit from this overlay:
- `donchian-strong-regime` — uses bear overlay (validated)
- Any custom trend-follow strategy

The overlay file itself is regime-agnostic — it provides functions for both bear and bull, and a range complement.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Superior-Trade](https://github.com/Superior-Trade)
- **Source:** [Superior-Trade/superior-skills](https://github.com/Superior-Trade/superior-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-superior-trade-superior-skills-regime-overlay
- Seller: https://agentstack.voostack.com/s/superior-trade
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.