analysis/README.md

# Signal Analysis Toolkit — how to run (2 commands on your Mac)

## Step 0 — Export your Telegram chat (one time, ~2 min)
1. Open **Telegram DESKTOP** (not phone) → open the Trade Copilot bot chat
2. ⋮ menu → **Export chat history** → format **JSON** → untick all media → Export
3. You get a folder with `result.json`

## Step 1 — Parse alerts
Put `parse_alerts.py`, `replay_signals.py` and `result.json` in one folder, then:
```bash
python3 parse_alerts.py result.json
```
→ writes `alerts.csv`, prints how many alerts + how many ≥8.8 conf.

## Step 2 — Replay against real BingX history
```bash
python3 replay_signals.py alerts.csv
```
- Fetches 1-minute candles from BingX public API (no keys needed; ~1-3 min for 50 alerts; candles cached in ./cache so reruns are instant)
- Writes **replay_results.csv** (per-alert: both scenarios, Lateness Index, 60m momentum, MFE/MAE, adj R/R) and **signal_report.md** (aggregates + buckets)

## Step 3 — Send both output files back to Claude/any AI for interpretation
The report feeds decision rules R1–R5 in evolution-plan/signal-analysis-plan.md (LI cutoff, TP policy, SL policy, threshold, skip-list) → those lock the automation config.

## Notes
- S1 "as-alerted" = limit at alert entry (12h fill window), TP1 target. S2 "your style" = market entry at alert moment (+slippage+fees), TP2 target. Both use alert SL. Same-candle TP+SL = counted as LOSS (conservative). 7-day cap.
- If very old alerts return NO_DATA, BingX 1m history ran out for that symbol — the report simply has fewer rows (noted per row).
- Both scripts are stdlib-only Python 3 — nothing to install.
- Self-test anytime: `python3 replay_signals.py --selftest`