# Historical replay and walk-forward strategy tournaments

Use this pattern after a paper-trading tournament framework exists but live market signals are sparse. It speeds strategy selection without enabling live orders.

## Trigger

- Multiple strategy presets exist from git history or hand-crafted candidates.
- Live/paper entries are rare, so waiting for real-time samples is too slow.
- You need evidence before promoting a candidate strategy.

## Pattern

1. **Replay presets, not historical commits**
   - Reconstruct strategy DNA as typed presets.
   - Do not execute old commits directly; old safety boundaries may be weaker.

2. **Side-effect-free replay engine**
   - Fetch/read candles into runtime cache under `~/.local/state/<Bot>/candle_cache/`.
   - Simulate entries/exits with pure strategy/risk functions.
   - Never call exchange order APIs from replay.
   - Write reports under runtime `reports/`, not Git.

3. **Use several lenses**
   - Aggregate score: total PnL, average PnL, win rate, profit factor, max drawdown.
   - Walk-forward segments: split history into N chronological slices and report segment PnL.
   - Stability score: fraction of positive segments.
   - Per-coin breakdown: detect if a candidate only wins on one coin.
   - Exit-reason breakdown: identify whether profit comes from V-shape exits, time stops, SLs, etc.

4. **Guard against coin leakage / overfitting**
   - Re-run rankings with and without the best coin.
   - Compare majors-only, alts-only, and full universe.
   - Treat one-coin dominance as a warning, not proof of edge.

5. **Parameter sweep after first evidence**
   - Sweep small neighborhoods around the candidate, e.g. trigger, time-stop, trailing distance.
   - Prefer robust parameter zones over one lucky point.
   - Keep sample-size warnings; do not tune from fewer than ~5 closed trades.

6. **Paper confirmation remains mandatory**
   - Replay can nominate candidates for paper tournament slots.
   - It does not authorize live trading.
   - Promote only after replay robustness and paper/live-market confirmation agree.

## Report shape

Recommended concise report rows:

```text
strategy_id: score, stability, n, winrate, avg_pnl, total_pnl, max_dd, profit_factor, segments=[...]
coins: COIN:n,total,winrate; ...
exits: reason:n,total; ...
```

## Pitfalls

- **Sparse flash-crash strategies may show zero trades on 15m candles**: retry with finer 5m or 1m candles before assuming the strategy is inactive.
- **A high score from one coin is fragile**: explicitly run coin-exclusion checks.
- **Replay fill assumptions are optimistic**: use replay for ranking hypotheses, not final profitability claims.
- **Tiny sample sizes lie elegantly**: label reports observation-only until enough closed trades exist.