# Historical Replay Tournaments for Trading Bots

Use this pattern after a paper-trading tournament exists but live market signals are sparse. The goal is to compare strategy presets faster without placing live orders.

## Core pattern

1. **Replay presets, not old commits**
   - Reconstruct strategy "DNA" from Git history into parameter presets.
   - Do not execute historical commits directly; old code may bypass current safety rails.

2. **Keep replay side-effect-free**
   - Historical replay must read candles and return metrics only.
   - It must not call live execution, `create_order`, Telegram senders, or mutate runtime trading state.
   - Cached market data belongs under `~/.local/state/<Bot>/candle_cache/`, not the repo.

3. **Use the same pure strategy functions as paper/live**
   - Reuse pure entry/exit functions where possible so replay and paper compare the same decision rules.
   - Convert each preset into a typed config before simulation.

4. **Run multiple time granularities**
   - A 15m replay can miss flash-crash setups that appear on 5m or 1m candles.
   - Start with 15m for speed, then re-run promising candidates on 5m/1m.

5. **Compare on risk-adjusted metrics**
   - closed trades, win rate, average PnL, total PnL
   - max drawdown
   - profit factor
   - average time in trade
   - exit-reason distribution
   - coin-level attribution

6. **Mark tiny samples as observation-only**
   - If `n < 5`, display the numbers but do not recommend strategy changes.
   - If a candidate wins only because of one trade or one coin, treat it as a hypothesis, not a champion.

7. **Promote cautiously into live paper tournament**
   - Move the top replay candidates into isolated paper portfolios.
   - Keep live orders disabled until out-of-sample and paper evidence agree.

## Useful implementation shape

- `historical_replay.py`: side-effect-free simulator + optional CLI
- `strategy_presets.json`: parameter presets from Git-history and new hypotheses
- `strategy_registry.py`: preset loading and preset-to-config conversion
- `reports/historical_replay_report.txt`: human-readable ranking under runtime state

## Pitfalls

- Backtests that look good because the candle interval hides intrabar drawdown.
- Ranking by total PnL only; this over-rewards rare high-risk strategies.
- Treating a 5-trade result as robust. Five trades is a minimum sanity check, not statistical proof.
- Letting replay fetchers spam exchange APIs; use runtime cache and request timeouts.
- Mutating the active paper state from a replay. Replay outputs should be reports, never trade journals used by live paper bots.