# 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`
  ```sql
  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.