Strategy & Shadow Testing Guide

# Strategy & Shadow Testing Guide

Last updated: 2026-07-17 (Kraken PF_XBTUSD live runtime)

Read this first. It explains what the bot does today, what is only being tested in shadow,
and what we might change later — only after evidence, not by gut feel.

================================================================================
1. WHAT THE LIVE BOT DOES (PRODUCTION)
================================================================================

Instrument: Kraken Futures PF_XBTUSD (BTC perpetual)
Strategy:   adaptive_long_short_score_v1
Timeframe:  1-hour candles for signals; 4-hour context for regime

The bot scores every closed hourly candle from 0–100 for LONG and SHORT separately.
It only enters when enough gates pass. It is maker-first on entries when possible.
Risk sizing comes from config (risk manager), not from the score alone.

REGIMES (4-hour context)
  strong_uptrend        — 4h ADX strong, price above rising 4h EMA20
  strong_downtrend      — price below falling 4h EMA20
  recovery              — mixed / transitional
  range_or_weak_trend   — 4h ADX below 25; chop and grind conditions

ENTRY GATES (checked in order — see dashboard Entry Gates table)
  1. regime_ok          — range regime rules (includes dynamic 4h ADX — see below)
  2. score_ok           — long or short score above threshold + extension limit
  3. hourly_adx_ok      — 1h ADX above minimum (default 20)
  4. volume_ok          — volume_ratio >= 0.80
  5. vwap_ok            — long above VWAP / short below VWAP
  6. conviction_raw_ok  — raw score high enough (not the diagnostic conviction_index)
  7. conviction_filter_ok — separation, margin, cost-edge, range volume 1.1 if in chop
  8. separation_ok      — winning side must lead opposing side by enough points

primary_blocker on the dashboard = first gate that failed.
hold_reason = plain English from the strategy.

DYNAMIC 4H ADX (deployed 2026-07-10 — replaces hard 22.0 cliff)
  Target:     4h ADX >= 22 normally required in range_or_weak_trend
  Soft band:  4h ADX between 17 and 22 can still pass IF:
              - 1h ADX >= 28 (hourly trend strong enough), AND
              - score separation >= 8 + (22 - 4h ADX) × 4
  Example:    4h ADX 21.3 + 1h ADX 48 + separation 38 → regime gate OPEN
  Hard floor: 4h ADX below 17 → always blocked in range

Status JSON field range_adx_gate shows relief_active, required_separation, etc.

EXITS (live)
  ATR stop, regime time stops (12h range / 36h trend), partial profit-taking,
  trailing logic, exchange protective stop sync.

================================================================================
2. DASHBOARD PAGES — WHAT TO USE
================================================================================

Home (index)
  Live health, scores, Entry Gates. A compact **Strategy Watchboard** banner (top)
  shows the current promote/don't-promote status with a link to the full page.
  Use this every hour after candle close as the main monitoring surface.

Watchboard (watchboard.html)
  Full **Strategy Watchboard** — what just went live, which shadows can promote,
  what is parked/retired, and the 24–48h operator checklist. Moved to its own
  page 2026-07-21 to keep Home uncrowded.

Strategy 2.0 (strategy2.html)
  Paper-only desk for the Strategy 2.0 experiment: $100 virtual account, long-only,
  24h horizon. Shows equity curve, entry gates (score / extension / funding veto),
  funding/OI/basis context, paper trades, a paper-vs-live comparison, and the 1-week
  promotion checklist. Reads strategy2.json from its own service — never sends real orders.

Shadow Results (simulation.html)
  Plain-language cards: what each shadow tests, what to watch, latest paper signal,
  and recent decisions. Differs-from-live chips surface the useful comparisons first.
  Compact table + outcome labels remain below.

Parameters
  Live config thresholds (ADX, volume, conviction, risk).

Decisions / Performance / Closed Trades
  What the bot decided and what actually closed.

Learning / Recommendations
  Advisory only — auto_apply is OFF. Never promotes to live by itself.

Exports / Review bundle
  Public reviewer package for external analysis.

Docs (this library)
  Operator guides only. Legacy research notes are hidden from the index.

================================================================================
3. SHADOW TESTS — NOT LIVE (PAPER / SIMULATED)
================================================================================

Shadow engines run on the same candles as production but never send broker orders.
They exist to answer: "Would a rule change have helped without blowing up risk?"

A. production_signal_simulator_v1
   Mirrors production gates with simulated taker fills.
   Use to see if production signals would have made money with simple fills.
   Caveat: live bot uses maker-first; simulator is pessimistic on costs.

B. Review candidate shadows (review_*_shadow_v1) — active set only
   Each tests one hypothesis. All run in parallel on the maintenance worker.

   | Shadow name                    | Hypothesis tested                          |
   |-------------------------------|---------------------------------------------|
   | trend_align                   | Require 1h/4h trend agreement               |
   | session_gate                  | Block entries in thin UTC hours             |
   | tight_short_no_range_aggressive | Higher short bar, no range, smaller size  |
   | mean_reversion                | Parked: VP fade VAL/VAH+RSI → POC (range)   |

   Retired 2026-07-20: uptrend_pullback_confirm, asymmetric_short_strict_gates
   (entry-timing cleanup; code kept for unit tests).
   Retired 2026-07-17: exit_bundle, smooth_thresholds, strict_conviction, pyramiding,
   kraken_pf_xbtusd_context, pullback_exhaustion, range_hourly_override,
   range_volume_profile_gate. Old RSI-bounce mean_reversion superseded 2026-07-19 by VP fade.

   Dashboard: Shadow Results → one card per shadow (What this tests / What to watch)
   Dashboard: Home → Range Entry Shadow Experiments (range_* only)

C. Offline backtest harness lean matrix (schema 6): baseline, patched_active_settings,
   strict_conviction, min_atr_008, tight_short, mean_reversion_vp. IOC/taker fill model.

D. Legacy shadows (early_reversal, setup_memory, trend_cycle, adaptive_regime)
   Removed from runtime 2026-07-16 — ignore any historical status keys.

================================================================================
4. THE 14-DAY OBSERVATION GATE (BEFORE ANY LIVE CHANGE)
================================================================================

We do NOT promote shadow logic to production until:

  1. At least 14 days of clean post-fix runtime logs (after 2026-07-09 reconciliation fix)
  2. Shadow variant beats production simulator on net PnL AND risk metrics
  3. Result is not from a tiny sample (rule of thumb: 20+ shadow closed trades minimum)
  4. Operator review of reviewer export + dashboard agrees

Current state (Jul 2026): gate NOT met. 0 closed live Kraken trades. Shadow sample ~15 trades, all net negative on small n. Learning is advisory only.

================================================================================
5. WHAT WE MIGHT ADJUST IF EVIDENCE SUPPORTS IT
================================================================================

Only change live after the gate above. Until then, adjust SHADOW variants to test ideas.

| Area              | Live today                         | Shadow testing it              | Promote if...                                      |
|-------------------|-------------------------------------|--------------------------------|----------------------------------------------------|
| Range 4h ADX      | Dynamic relief band (17–22)         | range_hourly_override          | Override wins PnL vs prod sim over 14d, stable DD |
| Range volume      | ratio >= 0.8; conviction 1.1 chop   | range_volume_profile_gate      | More entries, better outcome labels, not more stops |
| Volume (trend)    | 0.8 gate (~44% pass rate)           | strict_conviction (tighter)    | Only if tighter is better — unlikely near-term     |
| Short stops       | 2.5× ATR stop / 3.0 trail           | asymmetric_short_strict_gates  | Short shadow wins with fewer stop-outs             |
| Thresholds        | Regime-fixed long/short thresholds  | smooth_thresholds              | Smoother thresholds improve sim win rate + PnL     |
| Context scoring   | Standard composite                  | kraken_pf_xbtusd_context       | Context shadow consistently beats prod sim         |
| Exits             | Standard ATR + time stops           | exit_bundle                    | Faster exit of losers, keeps winners               |
| Pyramiding        | Off                                 | pyramiding                     | Clear uplift without concentration risk              |

DO NOT CHANGE WITHOUT STRONG EVIDENCE + OPERATOR SIGN-OFF
  - RISK_PER_TRADE_PCT, max exposure, leverage
  - atr_stop_multiple and exchange stop sync
  - Maker-first execution path
  - Kraken-only runtime lock (no Binance resurrection)
  - learning auto_apply (keep OFF)

================================================================================
6. HOW TO READ A BLOCKED ENTRY (EXAMPLE)
================================================================================

  long_score 93 / threshold 75  → score passes
  regime range_or_weak_trend
  range_adx_gate relief_active true → regime passes (dynamic ADX)
  volume_ratio 0.55 → volume_ok false → primary_blocker volume
  → Bot holds even with high score. Fix is shadow (profile gate) or evidence review, not impulse.

================================================================================
7. RELATED DOCS IN THIS LIBRARY
================================================================================

  Trading Operating Plan     — daily monitoring routine
  Known Issues               — open blockers and resolved fixes
  Active Runtime Contract    — broker lock and deployment rules
  Kraken Execution Checklist — proven vs unproven execution paths

Legacy overhaul plans, TODO queues, and archived Binance-era notes are hidden from
the docs index. They remain in the repository for history only.

================================================================================
8. QUICK REFERENCE — CONFIG KNOBS (env vars)
================================================================================

  ADAPTIVE_MIN_ADX_FOR_ENTRY=22
  ADAPTIVE_RANGE_ADX_SOFT_FLOOR=17
  ADAPTIVE_RANGE_HOURLY_ADX_RELIEF_MIN=28
  ADAPTIVE_RANGE_ADX_GAP_SEPARATION_PER_POINT=4
  SCORING_MIN_VOLUME_RATIO=0.80
  CONVICTION_RANGE_MIN_VOLUME_RATIO=1.10
  ADAPTIVE_ENTRY_HOURLY_ADX_MIN=20

See Parameters page for live values from the running bot.