analysis/EXECUTION-SCRIPT-FOR-SONNET.md

# EXECUTION SCRIPT — Signal Analysis Run
# For: Claude Sonnet (with computer control) · Written by: Fable 5 planning session · 2026-07-11
# Everything you need is in THIS folder: ~/Documents/trade-copilot-web/analysis/

## CONTEXT (30 seconds)
Trade Copilot (utkarsh's crypto scanner, live at utkarshpathak48-trade-copilot.hf.space) sends Telegram
alerts at confidence ≥8.8. We must measure how the last ~50 alerts ACTUALLY performed under Utkarsh's
real style (market entry at alert moment → exit 100% at TP2, SL as given, no time limit) vs as-alerted
(entry price → TP1). The analysis toolkit is BUILT AND TESTED (self-test + end-to-end verified).
Only the input data is missing: the alert history, which exists ONLY in Utkarsh's Telegram chat with the bot.
Full methodology: signal-analysis-plan.md (this folder). Your job: get the data, run the pipeline, interpret.

## STEP 1 — GET THE ALERT HISTORY (choose path A, fall back to B, then C)

### Path A (preferred): Telegram Desktop export
The App Store "Telegram" for macOS has NO export feature. The official "Telegram Desktop" (tdesktop) does.
1. Have Utkarsh download Telegram Desktop from https://desktop.telegram.org (or `brew install --cask telegram-desktop`).
2. UTKARSH logs in himself (QR scan from phone). ⚠ You must NEVER type his phone number, password, or login code — he does all authentication personally.
3. In Telegram Desktop: open the Trade Copilot bot chat → ⋮ (top right) → Export chat history →
   UNTICK all media → Format: **Machine-readable JSON** → Export. Result: a folder containing `result.json`.
4. Copy result.json into this analysis/ folder.

### Path B (if A fails): copy-paste transcript
1. In any Telegram client, Utkarsh selects the alert messages (or scrolls + selects all text) and copies them into a plain text file `alerts_paste.txt` in this folder. Timestamps matter: if the paste lacks dates, have him paste in chunks per day and note dates, or hover each message — TG copy usually includes "[DD.MM.YY HH:MM]" prefixes when copying multiple messages.
2. Adapt parse_alerts.py: add a txt mode that splits the paste into messages (each alert starts with 🟢 or 🔴 followed by "SYMBOL-USDT LONG/SHORT · X.X/10") and reads the nearest preceding "[date time]" stamp. The regexes in the script already match the alert body — you only add message-splitting + date capture. Keep output CSV columns identical.

### Path C (last resort): MTProto user-session script
Use Telethon with Utkarsh's own api_id/api_hash from my.telegram.org (HE creates them and HE enters the login code). Script: iterate messages from the bot chat, dump text+date to JSON matching Telegram-export shape, feed to parse_alerts.py unchanged. Do not store the session file afterwards; delete it.

## STEP 2 — RUN THE PIPELINE (2 commands, this folder)
```bash
cd ~/Documents/trade-copilot-web/analysis
python3 parse_alerts.py result.json          # → alerts.csv (prints count + how many ≥8.8)
python3 replay_signals.py alerts.csv         # → replay_results.csv + signal_report.md
```
- Scripts are stdlib-only Python 3. replay fetches public BingX 1m candles (no keys), caches in ./cache/, ~1–3 min for 50 alerts. Rerun-safe.
- Sanity first: `python3 replay_signals.py --selftest` must print SELFTEST OK.
- If some alerts print NO_DATA: BingX 1m history doesn't reach that far back for that symbol — acceptable, note the count. If MANY fail, retry those with interval 5m (edit fetch interval fallback or note it).
- If alerts.csv has <20 rows, tell Utkarsh how many were found before proceeding — maybe the export missed older history.

## STEP 3 — INTERPRET (this is the real deliverable)
Read signal_report.md + replay_results.csv and write `signal_verdict.md` answering EXACTLY these:
1. HEADLINE: S1 vs S2 win rate, total R, and net $ outcome on a $10 all-in account at 4× and 6× leverage
   (loss per losing trade ≈ leverage × SL-distance% × $10; compound sequentially in alert order; include the −0.1%×lev fee drag per trade).
2. LATENESS VERDICT: median Lateness Index; % of alerts with LI > 0.7; win rate per LI bucket.
   → Recommend the LI cutoff above which trades should be SKIPPED (this becomes automation config LI_LIMIT).
3. TP VERDICT: median MFE vs median TP2 distance (tp2_dist_r column); heartbreak rate (came ≥75% of way to TP2 then lost).
   → Recommend: keep TP2 / dynamic TP at k×median-MFE / TP1.5 midpoint — whichever maximizes total R recomputed from the MFE data.
4. SL VERDICT: MAE distribution of WINNING trades (s2_mae on wins). If many winners saw MAE > 0.8R, SL is too tight.
   → Recommend keep/widen (+ leverage compensation note).
5. THRESHOLD: compare 8.8–9.0 vs 9.0+ cohorts (conf column) on S2 expectancy → recommend CONF_MIN.
6. SKIP-LIST: any symbol or direction with ≥3 trades and 0 wins.
7. CAVEATS: n, confidence interval (95% CI ≈ ±1.96×sqrt(wr×(1−wr)/n)), regime concentration (all alerts from ~1 month).
Every recommendation must cite the numbers. If data contradicts Utkarsh's beliefs, say so plainly — he wants truth, not comfort.

## RULES
- Do NOT commit or push anything in the git repo without Utkarsh's explicit approval. Do NOT touch static/index.html, main.py, or any production file — this task lives entirely in analysis/.
- If .git/index.lock errors appear during any git command Utkarsh runs: `rm -f ~/Documents/trade-copilot-web/.git/index.lock` (known stale-lock issue).
- Never handle credentials/tokens/login codes — Utkarsh types those himself, always.
- You MAY spawn up to 3 sub-agents (per Utkarsh): sensible split = (1) data acquisition+parsing, (2) replay run+data QA, (3) interpretation+verdict writing. Only if genuinely useful — this is a linear task; agents optional.
- When finished: present signal_verdict.md + replay_results.csv + signal_report.md to Utkarsh, and tell him to give signal_verdict.md to the next planning session so the automation config (LI_LIMIT, TP policy, SL policy, CONF_MIN, skip-list = rules R1–R5) gets locked.

## WHAT'S ALREADY DONE (do not redo)
- Toolkit written + verified: parser (handles TG JSON mixed entities, skips heartbeats, 4h dedup), replay engine (self-test green: TP/SL/same-candle-loss/expiry/fees/MFE/MAE/lateness), e2e pipeline proven with injected candles. BingX kline API shape confirmed live.
- Methodology doc: signal-analysis-plan.md (metric definitions §4-5, decision rules §6).
- Automation blueprint waiting on your verdict: the planning session's evolution-plan/automation-architecture-v2.md.