trading_bot_v4/docs/FORWARD_SHADOW_PLAN.md

Forward Shadow Testing Plan

Objective

Validate Q≥95 + instant reversal + HTF + 5-candle exit strategy in real-time without risking capital before live deployment.

Shadow Mode Design

1. What Gets Logged

• All incoming signals (5m timeframe, non-manual):

  • signalQualityScore
  • direction (long/short)
  • HTF alignment status (5m vs 15m BlockedSignal)
  • Instant reversal flag (prior candle body reversal > threshold)
  • Final decision: WOULD_ENTER, BLOCKED_Q, BLOCKED_HTF, BLOCKED_INSTANT_REVERSAL, BLOCKED_OTHER

• Simulated trade lifecycle:

  • Entry price (current Pyth price at signal time)
  • TP1/TP2/SL levels (ATR-based)
  • Exit price and reason: TP1, TP2, TRAILING_SL, SL, TIME_EXIT_5_CANDLE
  • Simulated PnL after fees/slippage (use 0.04% taker + 0.5% slippage estimate)
  • Duration in candles
  • MFE/MAE

2. Storage

• New table: ShadowTrade

  CREATE TABLE "ShadowTrade" (
    id TEXT PRIMARY KEY,
    "createdAt" TIMESTAMP NOT NULL DEFAULT NOW(),
    symbol TEXT NOT NULL,
    timeframe TEXT NOT NULL,
    direction TEXT NOT NULL,
    "signalQualityScore" INTEGER NOT NULL,
    "htfAligned" BOOLEAN NOT NULL,
    "instantReversalDetected" BOOLEAN NOT NULL,
    "wouldEnter" BOOLEAN NOT NULL,
    "blockReason" TEXT,
    "entryPrice" NUMERIC(20,8),
    "exitPrice" NUMERIC(20,8),
    "exitReason" TEXT,
    "simulatedPnL" NUMERIC(10,2),
    "durationCandles" INTEGER,
    "maxFavorableExcursion" NUMERIC(10,2),
    "maxAdverseExcursion" NUMERIC(10,2),
    "exitedAt" TIMESTAMP
  );
  

3. Implementation Steps

Step 1: Add Shadow Mode Flag

• ENV: SHADOW_MODE=true
• When true, check-risk and position-manager log decisions but do not place orders.

Step 2: Instant Reversal Detection

• In check-risk, before quality gate:
  • Fetch last completed 5m candle (from Pyth or cache).
  • Compute body size: abs(close - open).
  • Compute reversal: if signal is long and prior candle body was strong down (close < open and body > k·ATR), flag instantReversalDetected=true.
  • Similarly for short.
  • Suggested k=0.5 initially; tune based on results.

Step 3: HTF Alignment Check

• In check-risk, after quality gate:
  • Fetch most recent 15m BlockedSignal direction.
  • If 5m signal direction == 15m blocked direction AND quality < 85, flag htfBlocked=true.
  • Else htfAligned=true.

Step 4: Shadow Entry Decision

• Combine checks:
  • wouldEnter = (Q >= 95) AND htfAligned AND !instantReversalDetected AND (other risk checks pass)
  • If wouldEnter=false, set blockReason and write to ShadowTrade with entryPrice=null.
  • If wouldEnter=true, write to ShadowTrade with entryPrice and start shadow monitoring.

Step 5: Shadow Monitoring

• Position Manager polls every 10s:
  • Fetch current Pyth price.
  • Check TP1, TP2, SL, trailing SL (same logic as live).
  • Check 5-candle time: if 25 minutes elapsed and MFE < $30, exit with TIME_EXIT_5_CANDLE.
  • On exit, compute simulatedPnL (with fees/slippage) and update ShadowTrade.

Step 6: Daily Reports

• Cron job or API endpoint /api/trading/shadow-report:
  • Aggregate ShadowTrade by day:
    • Total signals, would-enter count, per-block-reason counts.
    • Win rate, avg PnL, total PnL, max drawdown.
    • Per-direction breakdown.
  • Push to Telegram or email.

4. Validation Criteria (4–6 weeks, ≥100 trades)

Go criteria:

• Net simulated PnL > 0 after all costs.
• Win rate > 40% or expectancy > $5/trade.
• Max drawdown < 20% of starting capital.
• Return-to-drawdown > 1.0.
• Metrics stable across 2-week rolling windows.

No-go criteria:

• Net PnL < 0 or expectancy < 0.
• Max drawdown > 30%.
• Hit rate < 35% with large tail losses.
• Sensitivity tests show parameter brittleness.

5. Dashboard (Optional)

• Build Next.js page /shadow-dashboard:
  • Real-time counters: signals today, would-enter today, blocked by reason.
  • PnL chart: cumulative simulated equity curve.
  • Table: last 20 shadow trades with entry/exit/PnL.
  • Filters: date range, direction, block reason.

6. Rollout After Validation

• Disable shadow mode: SHADOW_MODE=false.
• Deploy unified Q≥95, instant reversal filter, HTF enforcement, 5-candle exit to live check-risk and position-manager.
• Monitor live logs for first 48h with small position sizes.
• Compare live vs shadow metrics; revert if divergence or losses exceed kill-switch.

Files to Create/Edit

1. prisma/schema.prisma: Add ShadowTrade model.
2. app/api/trading/check-risk/route.ts: Add instant reversal + HTF checks, shadow logging.
3. lib/trading/position-manager.ts: Add shadow monitoring loop and 5-candle exit.
4. app/api/trading/shadow-report/route.ts: Daily aggregation endpoint.
5. app/shadow-dashboard/page.tsx: (Optional) Real-time UI.
6. .env: Add SHADOW_MODE=true.

Timeline

• Week 1: Implement shadow logging, instant reversal, HTF checks.
• Week 2: Deploy shadow mode; verify logging and first results.
• Weeks 3–6: Collect ≥100 shadow trades; daily review.
• Week 7: Validation decision; if pass, deploy live with small size.
• Week 8: Scale up if live matches shadow.

Risk Mitigations

• Shadow mode ensures no capital at risk during validation.
• Kill-switches remain active in live deployment.
• Telegram alerts for anomalies (slippage spikes, API errors, sudden drawdown).
• Rollback plan: revert to current thresholds (90 long / 85 short) within 5 minutes if loss > $50 in one day.