atm-backtesting/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this repo is

A **manual Excel-first backtesting journal** for blackbox trading signals (M2D strategy primarily). There is no live data ingestion, no broker integration, no vision pipeline — the user types each trade into `data/backtest.xlsx` and Excel formulas compute everything else. The Python codebase is one script that regenerates the workbook template.

The project was recently rebooted (commit `0179217`) — an earlier vision/screenshot extraction pipeline was removed in favor of this manual Excel approach. Do not reintroduce vision/OCR/auto-extraction features unless explicitly asked.

Documentation and UI strings are in **Romanian**; keep them Romanian when editing.

## Commands

```powershell
pip install openpyxl                       # one-time
python scripts/generate_template.py        # regenerate data/backtest.xlsx (Config + Trades only)
python scripts/generate_dashboard.py       # regenerate data/Dashboard.xlsx din backtest.xlsx
```

`refresh_dashboard.bat` (rădăcina repo) = wrapper dublu-click: rulează `generate_dashboard.py` și deschide `Dashboard.xlsx`.

No test suite, linter, or build step exists. The only "build" is regenerating the Excel.

**Destructive caveat**: `generate_template.py` **overwrites `data/backtest.xlsx` with no prompt**. The user's logged trades live in that file. Before running it (or asking the user to), confirm they have a backup or that the file is empty/sample-only.

## Architecture

Three artifacts work together; understand all three before editing any:

### 1. `scripts/generate_template.py` — the only code

`build_workbook()` builds `data/backtest.xlsx` = **2 sheets only** (Config + Trades). `build_dashboard()` still lives here but is **no longer added to backtest.xlsx** — it is reused by `scripts/generate_dashboard.py` to build the separate `data/Dashboard.xlsx` (see "Analiză combinată" below).

- **Config** sheet — editable params (Account Size, Risk %) and dropdown source lists.
- **Trades** sheet — `MAX_ROWS=500` pre-populated rows. Yellow cells = user input (date, time, strategy, indicator, TF, direction, SL/TP %, outcome). Blue cells = derived via formula (Zi, Sesiune, then per-strategy `R_*`, `$_*`, `Bal_*`). Grey cells = helper columns (`Win_*`, `Peak_*`, `DD_*`) consumed by Dashboard.
- **Dashboard** (`build_dashboard`, emitted into the separate `Dashboard.xlsx`) — reads from Trades ranges via `SUMIF`/`AVERAGEIF`/`COUNTIF`; renders metrics table, glossary, per-Strategy/Indicator/Direction breakdowns, prop compliance. **No formula-based ferestre grid** (removed — that window scan is now the python auto-scan in the `Ferestre` sheet; see "Analiză combinată" below) and **no equity-curve chart** in the Dashboard sheet itself.

Column-name → letter mapping is held in the `COL` dict, built from `TRADES_HEADERS = INPUT_HEADERS + DERIVED_HEADERS + HELPER_HEADERS`. **Never hardcode column letters** — adding/reordering a header shifts every letter. Always look up via `COL["..."]`.

### 2. The 5 management strategies — core domain concept

Every trade is simulated through 5 management overlays in parallel. Keys (`STRAT_KEYS`) and their R-multiple formula builders (`R_FN`) must stay in sync:

| Key | Label | Formula entry point |
|---|---|---|
| `tp0only` | TP0 only | `_f_r_tp0only` |
| `tp1only` | TP1 only | `_f_r_tp1only` |
| `tp2only` | TP2 only | `_f_r_tp2only` |
| `hybrid_be` | Hybrid + BE | `_f_r_hybrid_be` |
| `hybrid_nobe` | Hybrid no BE | `_f_r_hybrid_nobe` |

For each strategy and each trade row, six columns are emitted: `R_*`, `$_*`, `Bal_*`, `Win_*`, `Peak_*`, `DD_*`. Adding a 6th strategy means: append to `STRAT_KEYS` + `STRAT_LABELS`, add an `_f_r_<key>` formula, register it in `R_FN`, and the rest (Trades columns, Dashboard table column, equity-curve series) flows automatically. The R-multiple formulas encode trader assumptions — the truth table is documented in `README.md` and `STOPPING_RULE.md`; changing one is a strategy decision, not a refactor.

### 3. Session derivation (M2D-specific)

The `Sesiune` column is computed by `_f_session` from `Data` + `Ora RO` (Romanian time) using nested IFs encoding the M2D session windows (A1/A2/A3/B/C/D/Other). The buckets and times come from `strategie_M2D.md`. If asked to add a new session bucket, edit `_f_session` and `SESSIONS` together — Dashboard's PER SESIUNE breakdown iterates over `SESSIONS`.

## Decision gates — `STOPPING_RULE.md`

`STOPPING_RULE.md` is a **signed document** (the user committed it as a commitment). It defines GO LIVE / EXTEND / ABANDON thresholds: `N≥40`, `WR≥55%`, `Expectancy≥+0.20R`. Treat these numbers as fixed unless the user explicitly asks to renegotiate them — do not "improve" them in passing.

## Analiză combinată — `Dashboard.xlsx` (scripts/generate_dashboard.py)

`backtest.xlsx` (editat zilnic) = doar Config + Trades (~0.8 MB, rapid la salvat). TOATĂ analiza trăiește într-un **singur** fișier read-only `data/Dashboard.xlsx`, generat la comandă din backtest.xlsx de **un singur script** `generate_dashboard.py`. (Istoric: erau două fișiere cu două scannere de ferestre — `Dashboard.xlsx` pe formule + `Ferestre_v2.xlsx` python cu ferestre A/B/W hardcodate; au fost combinate. `generate_ferestre_v2.py` a fost șters.)

**Reluare după ce Marius adaugă tranzacții noi:**
```powershell
# întâi: deschide & SALVEAZĂ backtest.xlsx în Excel (populează cache-ul R_/$_/Bal_)
python scripts/generate_dashboard.py      # sau dublu-click refresh_dashboard.bat
```
`generate_dashboard.py` citește `backtest.xlsx` **read-only, `data_only=True`** — ia valorile DEJA calculate de Excel (nu recalculează formule). **Constrângere:** dacă nu ai salvat în Excel după ultima editare, cache-ul lipsește și analiza iese goală.

**Sheet-urile din `Dashboard.xlsx`:**
- `Config` — inputurile reale (lot, limite prop) copiate din backtest + formule (`build_config()`).
- `Trades` — snapshot static ascuns (valori, nu formule), ca să țină backtest.xlsx mic.
- `Dashboard` — metrici 5 manageri + breakdown-uri (strategie/indicator/direcție) + prop compliance. **Formule** Excel (recalculează live la schimbarea Config). Grila veche de ferestre pe formule (`FERESTRE CANDIDATE` + `TOP 20`, ~mii de coloane-helper = cauza dimensiunii) a fost **scoasă** din `build_dashboard()`.
- `Ferestre` — **auto-scan python** edge × durată × fiabilitate (valori statice). Vezi mai jos.
- `date_grafic` — sursa curbei de echitate din sheet-ul Ferestre.

### Sheet-ul Ferestre — auto-scan (NIMIC hardcodat)

Construit de `build_ferestre()` în `generate_dashboard.py`. Găsește **fereastra (ora RO) cu cel mai bun edge** fără să spargă contul prop:
- **Grilă generativă** la 15 min (start 16:30–22:00, durată 45min–capăt 23:00, filtru {toate, prima}), scanată pe **toate cele 5 manageri**; pe fiecare fereastră raportează managerul cu cel mai bun ExpR dintre cei non-breach. Grila la 15 min e **suprasetul** vechilor două grile (cea Dashboard la 30 min nici nu vedea ferestrele pe :15/:45).
- **Recomandări derivate din date** (etichete = fereastra calculată, nu nume fixe), în familii cu gradații — funcția `recommend()`, praguri în constantele `EDGE_*`/`ROBUST_*`/`VOLUM_*`: **EDGE 45min/1h/1h30** (cea mai profitabilă fereastră la fix acea durată → cea mai mică = cea mai scurtă perioadă profitabilă), **ROBUST 1/2/3** (cel mai bun ExpR pozitiv în toate / ≥80% / ≥60% din luni, N≥40), **VOLUM (max N)** + **VOLUM compact** (cel mai mare volum profitabil, resp. cea mai scurtă fereastră tot cu volum relevant). Dedup pe (start,end) → un geam apare o singură dată. Câte se validează în adâncime = `FERESTRE_MAX_VARIANTS` (BRUT + recomandări + top-N profitabile).
- **Validări** (recalculate de fiecare dată): Forward 1 (lunar), Forward 2 (train/test 70/30), walk-forward (3 felii), bootstrap CI 95%, calendar NFP, grafic echitate pe primele 2 recomandări.
- Limitele prop (cont/daily/max) se citesc din Config (B9/B12/B14), fallback $50k/4%/7%.

**Fără concluzii hardcodate — NU le re-introduce.** Versiunea veche avea ferestrele A/B/W și concluziile lipite în script dintr-o analiză LLM anterioară; se învecheau la fiecare lot nou. Acum totul se re-derivă din date. Ferestrele bune reapar singure dacă rămân cele mai bune (ex. ROBUST 19:45–21:45 hybrid_be = fostul „B", re-găsit automat).

**Avertisment overfit:** scanul pe toate cele 5 manageri × mii de ferestre poate scoate în top combinații fragile (ex. `TP2 only` pe N mic = ExpR umflat de varianță). De-aia validările (bootstrap CI, lunar, train/test, walk-forward) sunt în același tabel — citește-le împreună cu ExpR-ul, nu doar vârful.

**ÎNAINTE de a interpreta — verifică typo-uri în Trades** (TP%/SL% cu zecimală lipsă umflă fals edge-ul). Cele găsite și corectate manual: #314 (TP2 17→0.17), #298 (TP0 0.5→0.05), #240 (TP1 0.8→0.08), #182 (ordine TP0/TP1 inversată → 0.06/0.10), #338 (TP1 0.011→0.11; era SL deci R neschimbat). La date noi, caută valori TP/SL ≥1 sau TP0>TP1>TP2 inversate și confirmă cu Marius înainte de a corecta.

**Sincronizare:** la comandă (rulezi scriptul/bat-ul), NU live. Marius a ales explicit acest model.

**Migrare unică — `scripts/strip_dashboard.py`:** scoate sheet-ul Dashboard din `backtest.xlsx` existent (39 MB → ~0.8 MB). NU folosește openpyxl pentru rescriere (ar șterge cele 12 dropdown-uri **x14** din Trades). Face **chirurgie pe zip**: elimină doar partea Dashboard + drawings/charts + `calcChain.xml` + definedName-ul orfan, lăsând XML-ul Config/Trades byte-cu-byte intact. Cere `--yes` și face backup automat. Alternativă 100% sigură: șterge tab-ul Dashboard manual în Excel (click-dreapta → Delete → Save). **Rulează doar cu acordul lui Marius** (e destructiv pe fișierul real).

## Reference docs

- `strategie_M2D.md` — M2D setup rules (color-coded dot bands on TF mare/mic, SL/TP placement, session filters).
- `calendar_evenimente.yaml` — manual news calendar (FOMC/NFP/CPI). Read-only context; not parsed by code.
- `README.md` — user-facing workflow + R-multiple truth table.

## Working in this repo

- The user is **Marius**, a discretionary trader doing his own backtest, not an engineer building a product. Prefer minimal, legible changes to the Excel template over abstractions. The audience is one person logging trades, not a team.
- When changing formulas in `generate_template.py`, regenerate the workbook and inspect at least one row's outputs before declaring done — a formula typo silently breaks the entire downstream Dashboard.
- The git user is `Marius` on branch `master` (not `main`); PRs are not the workflow here, direct commits to `master` are.

## gstack

Use the `/browse` skill from gstack for all web browsing. Never use `mcp__claude-in-chrome__*` tools.

Available gstack skills: `/office-hours`, `/plan-ceo-review`, `/plan-eng-review`, `/plan-design-review`, `/design-consultation`, `/design-shotgun`, `/design-html`, `/review`, `/ship`, `/land-and-deploy`, `/canary`, `/benchmark`, `/browse`, `/connect-chrome`, `/qa`, `/qa-only`, `/design-review`, `/setup-browser-cookies`, `/setup-deploy`, `/setup-gbrain`, `/retro`, `/investigate`, `/document-release`, `/document-generate`, `/codex`, `/cso`, `/autoplan`, `/plan-devex-review`, `/devex-review`, `/careful`, `/freeze`, `/guard`, `/unfreeze`, `/gstack-upgrade`, `/learn`.