# Trade Forensics Runbook

Use this whenever live trades look wrong. The goal is to avoid guessing: every
strategy or prompt change should be tied to fills, OHLC, LLM reasoning, and the
local orderflow research notes.

## Fast Report

```bash
cd /root/hl-bot-v2
set -a; . /run/hl-bb-live.env; set +a
scripts/trade_forensics.py --since 2026-05-23T15:59:00 --out data/reports/latest-forensics.md
```

Open `data/reports/latest-forensics.md` and check:

- `wrong_quickly`: direction failed almost immediately.
- `gave_back_large_mfe`: trade was right first, but TP/management was bad.
- `borderline_noise_stop` / `stop_below_atr`: stop too close for current noise.
- `breakout_without_retest_text`: LLM chased a break instead of waiting for retest/acceptance.
- stale websocket values in the matched `llm_decision` market summary.

## What To Compare

1. Fills: actual entry/exit, fees, net PnL, manual vs TP/SL close.
2. OHLC after entry: MFE, MAE, whether SL was a wick hunt or the thesis was wrong.
3. LLM decision: `playbook_match`, `level_reasoning`, `exit_plan`, and raw response.
4. Deterministic gates: `research_gate`, `exit_plan_gate`, `risk_reject`.
5. Research notes:
   - `/root/wiki/raw/orderflow-sl-tp-placement-research-2026-05-23.md`
   - `/root/wiki/raw/hyperliquid-data-strategy-playbook-2026-05-23.md`
   - `/root/wiki/raw/hyperliquid-orderflow-research-2026-05-23.md`
   - `/root/wiki/raw/orderflow-trading/03-strategies.md`

## Patch Rules

- Do not loosen gates just to create more trades.
- If WS book or tape is stale/empty, the trade is not orderflow-confirmed.
- Do not trust LLM-reported alignment scores; recompute side alignment locally.
- Breakouts need retest/acceptance or fresh multi-window initiation.
- Stops must be beyond structure and noise, currently ATR(14) x configured multiplier plus 1m/5m range checks.
- After a loss, same coin/side and immediate flips are blocked by cooldown.

## Current Live Safety

- Entries use IOC, not GTC, so a non-filled entry cannot sit forgotten and fill later.
- If IOC entry does not fill, the adapter cancels the planned TP/SL cloids and raises.
- Live sync journals exchange closes from `userFills` before removing local manager state.
- Break-even and profit-lock are disabled by config; live trades should exit at original TP/SL unless manually closed.
