# Live Forensics Runbook

Use this when the live bot has been running and we need a fast, repeatable
post-trade analysis before changing strategy code.

## Command

From `/root/hl-bot-v2`:

Fast all-in-one loss diagnosis:

```bash
set -a
. /run/hl-bb-live.env
set +a
scripts/loss_diagnosis.py --since "2026-05-24 13:27:53"
```

Rolling window:

```bash
set -a
. /run/hl-bb-live.env
set +a
scripts/loss_diagnosis.py --hours 12
```

Add `--show-candles` when you need the raw OHLC timeline around each matched
trade. This is verbose.

Missed/rejected candidate replay plus LLM lesson file:

```bash
set -a
. /run/hl-bb-live.env
set +a
scripts/loss_diagnosis.py --hours 72 --missed-candidates 20 --write-lessons data/ohlc_lessons.json
```

This checks rejected candidates with concrete entry/stop/target against later
OHLC. It separates "reject saved money" from "candidate later hit target but
the LLM plan used a too-tight stop or undersized target". The generated
`data/ohlc_lessons.json` is loaded by the LLM prompt on process start.

Older detailed report:

```bash
.venv/bin/python scripts/live_forensics.py \
  --since "2026-05-23 06:30" \
  --address 0x888BF668C36720dEA394C48fDa0feB2F91EA6B94 \
  --ohlc
```

For a rolling window:

```bash
.venv/bin/python scripts/live_forensics.py --hours 12 --address 0x888BF668C36720dEA394C48fDa0feB2F91EA6B94 --ohlc
```

The script is read-only. It uses Hyperliquid `/info` calls:

- `userFills`
- `clearinghouseState`
- `candleSnapshot` when `--ohlc` is set

## What To Check First

1. `Net realized + Open unrealized`
2. `By Coin`: identify which coins/sides are paying and which are bleeding
3. `Trade Reconstruction`: inspect MFE/MAE per trade
4. `Research Gate Warnings`: compare entries against orderflow playbook rules

Important: exchange fills can include manual closes. Do not call a winner
"bot edge" unless `exit_source` shows a bot-managed level match or the raw
logs confirm the bot closed it.

## Research Rules Applied

Sources:

- `/root/wiki/raw/orderflow-basics.md`
- `/root/wiki/raw/orderflow-strategies.md`
- `/root/wiki/raw/orderflow-comprehensive-summary.md`
- `/root/wiki/raw/hyperliquid-orderflow-research-2026-05-23.md`
- `/root/wiki/raw/hyperliquid-data-strategy-playbook-2026-05-23.md`

Core checks:

- Trend continuation should be entered on pullback, retest, failed rally, VWAP/POC hold, or acceptance breakdown. Do not chase current mid just because tape is aggressive.
- Countertrend mean reversion needs sweep/reclaim, absorption, VWAP/VPOC reclaim, or clear price response. Being far from VWAP alone is not enough.
- Tape must include price response. Buy tape without price lifting or sell tape without price falling is absorption/trap risk.
- Longs with high ask absorption and shorts with high bid absorption are blocked or need opposite-side evaluation.
- Fees matter. A gross tiny win can still be a net loss.

## Current Known Bot Weaknesses

- Daily trade counters are in memory. A service crash/restart can reset the limit and allow overtrading.
- The journal records entries and stop updates, but live closes must be reconstructed from exchange fills.
- Prompt `level_reasoning` improves explainability, but it does not enforce edge by itself.
- Current entries often happen at `current mid`; research prefers waiting for confirmation levels.

## Patch Priority

1. Persist/rebuild daily trade and loss counters from exchange fills or journal on startup.
2. Add an orderflow research gate after the LLM and before `RiskManager.check`.
3. Journal live exchange close events with fill PnL/fees so learning can update without manual reconstruction.
4. Tighten prompt: require pullback/retest/reclaim/failed-push wording for trend continuation and countertrend entries.
5. Add side/coin cooldown after repeated same-setup losses.
