# Commentary review & correction loop

Turn expert review of the broadcast commentary into structured data — both the **eval set** an AI
commentary version must pass, and the **few-shot gold examples** the Level-4 AI author learns from.
This is the "you can start now" loop: the reviewer marks up lines; the engine measures itself against
those marks. See [`docs/V3-broadcast.md` §0](../../../../docs/V3-broadcast.md) for the AI roadmap.

Tool: [`demo/export/review_commentary.py`](../../export/review_commentary.py).

## 1. Export a race's commentary to review

```
.venv-demo/Scripts/python.exe v3/broadcast/demo/export/review_commentary.py --race gsys08 --lang en
```

Writes `gsys08_en.csv` here — one row per spoken line, with the context needed to judge it without
watching the render: race-clock (mm:ss vs the gun), Caller/Analyst, event type, who leads, the leg's
point of sail, and the boats the line is about. (Omit `--race` for the demo `real.json`; omit `--lang`
for every language.)

## 2. Mark it up (the reviewer)

Open in Excel and fill three columns per line:

- **verdict** — `ok` · `wrong` (factually wrong) · `dull` (irrelevant/filler) · `irrelevant`
- **better** — what a good caller would have said instead (the gold line). Most valuable for `wrong`/`dull`.
- **tag** — optional reason: `fact` · `repeat` · `timing` · `tone` · `names` · `other`

## 3. Ingest the marked-up file

```
.venv-demo/Scripts/python.exe v3/broadcast/demo/export/review_commentary.py --ingest .../gsys08_en.csv
```

Prints the **report card** (% ok / wrong / dull / irrelevant — the reviewer's gut-feel made real,
per race) and writes `gsys08_en.corrections.json`: the lines that were wrong/dull/irrelevant, what was
said, and the gold `better` line — the dataset that drives Level-4.

Commit the **filled-in CSVs + `*.corrections.json`** here (they're the data); the blank exports are
regenerable and need not be committed.