perfect-storm-options-trader

What this skill does

# Perfect Storm Options Trader — OpenClaw Skill v2

> **Paper trading only.** This skill must never execute against a live brokerage
> endpoint. If live credentials or a live base URL are detected at any point,
> **stop immediately** and request explicit human confirmation before proceeding.

---

## 1. Purpose and Scope

This skill defines the complete **behavioral, governance, and execution spec** for
an OpenClaw agent running the Perfect Storm (PS+/PS−) options strategy.

The agent's mandate in one sentence:
> Trade only when setup quality, market regime, liquidity, and risk conditions
> all align strongly enough to justify premium risk. "No trade" is a valid—
> often preferred—output.

The agent produces one of five symbolic states per scan cycle per symbol:

| State | Meaning |
|-------|---------|
| `IGNORE` | Fails pre-filter; stop evaluating this symbol |
| `WATCHLIST` | Interesting but not yet ready; monitor next cycle |
| `ARM_ENTRY` | Setup is forming; prepare contract selection and size |
| `ENTER` | All gates pass; submit limit order |
| `EXIT` | Existing position must be reduced or closed now |

---

## 2. Canonical Reference Files

| File | Purpose |
|------|---------|
| `references/AGENTS.md` | Full strategy rulebook: universe, setup definitions, indicator stack, sizing/exit logic, journaling schema |
| `references/risk_config.yaml` | Hard limits: account config, per-trade risk, daily/weekly drawdown caps, option filters |
| `scripts/alpaca.mjs` | Minimal Alpaca REST helper for account state, positions, orders |

**Always load `references/risk_config.yaml` at agent startup.** If the file is
missing or unreadable, halt and request it before doing anything else.

---

## 3. Operating Workflow

Execute these phases in strict order. Any gate failure returns the symbol to
`IGNORE` or `SKIP` and logs the reason.

### Phase 0 — Boot and Safety Checks

```
1. Load risk_config.yaml — halt if missing
2. Confirm APCA_API_BASE_URL == https://paper-api.alpaca.markets — halt if live
3. Fetch account state via scripts/alpaca.mjs account
4. Compute current portfolio heat (open positions × notional risk)
5. Check daily/weekly loss counters — halt new entries if limits hit
6. Confirm data feeds are live and spread data is fresh (< 60s)
```

If **any** safety check fails → set `agent_state = HALTED`, log reason, do not
scan.

### Phase 1 — Market Regime Classification (Gate 1)

Classify the broad market environment using SPY/QQQ as primary proxies:

| Regime | Signal Characteristics | Allowed Bias |
|--------|----------------------|--------------|
| `TRENDING_BULL` | Price > 20/50/200 EMA stack; ADX > 20; shallow pullbacks | PS+ calls preferred |
| `TRENDING_BEAR` | Price < EMA stack; ADX > 20; weak bounces | PS− puts preferred |
| `CHOP` | Price whipping around EMAs; ADX < 20; no follow-through | Reduce size 50%; raise confidence threshold to `exceptional_score` |
| `SHOCK` | VIX spike > 25%; spreads blown out; correlation breakdown | Halt new entries |

**Default rule:** If regime cannot be clearly classified → `CHOP`.
In `CHOP` or `SHOCK`, only enter if `confidence_score >= exceptional_score` from
`risk_config.yaml` (default 85).

### Phase 2 — Universe Scan and Pre-Filter (Gate 2)

Start from the approved universe in `references/AGENTS.md`. For each symbol apply:

```
✓ Underlying price >= min_stock_price (config)
✓ Avg daily share volume >= min_avg_daily_share_volume (config)
✓ ATR% >= min_atr_percent (config)
✓ Relative volume >= min_relative_volume (config)
✗ Earnings within avoid_earnings_days_before days → SKIP
✗ Macro event within avoid_macro_minutes_before minutes → SKIP
✗ Abnormal spread expansion detected → SKIP
```

Rank survivors by setup readiness, cap at `max_symbols_ranked_per_cycle`.

### Phase 3 — Perfect Storm Detection and Scoring (Gate 3)

#### PS+ Bullish Checklist

Score one point per condition met. Maximum 10 points.

1. Higher timeframe (30m/60m) trend is bullish (price > 50 EMA, ADX rising)
2. Execution timeframe (3m/5m/15m) trend aligns (price > 20 EMA)
3. CCI recovering from oversold zone (< -100) and turning upward
4. PPO / MACD momentum improving (histogram expanding in bullish direction)
5. ADX > 20 and +DI crossing above −DI, or strengthening in that direction
6. Price reclaiming or bouncing from key structure (VWAP, prior day high/low, S/R)
7. Higher low visible on execution timeframe — uptrend structure intact
8. Volume expansion on the recovery candle or breakout bar
9. Entry is NOT after a fully extended spike (check ATR %, room to target)
10. Options chain passes: spread ≤ config max, OI ≥ config min, volume ≥ config min

#### PS− Bearish Checklist (mirror)

1. Higher timeframe trend is bearish (price < 50 EMA, ADX rising)
2. Execution timeframe trend aligns (price < 20 EMA)
3. CCI declining from overbought zone (> +100) and turning downward
4. PPO / MACD momentum weakening (histogram contracting or flipping negative)
5. ADX > 20 and −DI crossing above +DI, or strengthening in that direction
6. Price rejecting key structure (VWAP, prior day low, R zone)
7. Lower high visible on execution timeframe — downtrend structure intact
8. Volume expansion on the rejection candle or breakdown bar
9. Entry is NOT after a fully extended drop
10. Options chain passes same liquidity checks

#### Scoring → Action Map

| Raw Score | Normalized (×10) | Action |
|-----------|-----------------|--------|
| < 7 | < 70 | `SKIP` |
| 7–8 | 70–80 | `WATCHLIST` or `ENTER` at reduced size |
| 8–9 | 80–90 | `ENTER` at standard size |
| 9–10 | 90–100 | `ENTER` at full size (still within hard limits) |

### Phase 4 — Contract Selection (Gate 4)

```
DTE:    preferred_dte_min (7) to preferred_dte_max (21)
        0-DTE only if allow_0dte: true in config (default false)

Delta:  delta_min (0.35) to delta_max (0.60) for standard directional trades
        Tighter end (0.45–0.65) for strong trend-continuation setups
        Day-trade / fast scalp: 0.25–0.45 only if spread/fill quality excellent

OI:     >= min_open_interest (config)
Volume: >= min_option_volume (config)
Spread: bid-ask spread as % of mid <= max_bid_ask_spread_percent (config)
```

When multiple contracts qualify, rank by:
1. Tightest spread
2. Highest open interest
3. Delta closest to target band center
4. Cleanest fill probability (avoid strikes with fragmented chain)

Reject if option premium is so low that one tick is > 5% of premium (lottery
contract risk).

### Phase 5 — Position Sizing (Gate 5)

Use fixed-fraction risk logic:

```
max_risk_dollars = account_equity × (max_risk_per_trade_percent / 100)
contracts_raw   = floor(max_risk_dollars / (premium_per_contract × 100))
contracts       = min(contracts_raw, max_contracts_derived_from_position_pct)
```

Adjustments:
- **CHOP regime:** × `chop_size_multiplier` (0.5)
- **After N consecutive losses:** × `reduced_size_multiplier` (0.5) once
  `reduce_size_after_consecutive_losses` threshold is hit
- **Score < 80:** reduce size by 25%

If `contracts < 1` after adjustments → `SKIP` (minimum size violates risk rules).

Also check:
- `max_open_positions` not exceeded
- `max_positions_per_symbol` not exceeded
- Adding this position does not push `portfolio_heat > max_portfolio_heat_percent`

### Phase 6 — Execution Plan

```
Order type:    LIMIT (always)
Limit price:   mid-price of bid-ask at evaluation time, or slight edge inside mid
Chase guard:   if current ask has moved > do_not_chase_percent (3%) above
               entry plan → cancel and re-evaluate
Fill timeout:  cancel_if_not_filled_seconds (45)
```

Never submit a market order for options. Never re-chase a missed fill blindly.

### Phase 7 — Position Management and Exit Logic

#### Stop Definitions (pre-define before entry, never after)

Choose the tightest applicable stop:

1. **Underlying structure stop:** invalidation level on chart (break of VWAP, EMA,
   or key S/R) → convert to equivalent premium loss estimate
2. **Premium stop:** `max_option_premium_loss_percent` (3