# Script usage

The scripts are deterministic helpers. They prepare evidence and render the final
artifact; the Skill instructions still own KPI confirmation, interpretation, and
action judgment.

## 1. Normalize a report

```bash
python3 scripts/analyze_report.py report.xlsx \
  --analysis-date 2026-08-25 \
  --retention-lag-days 1 \
  --output /tmp/report.analysis.json
```

Supported inputs are `.xlsx`, `.csv`, and `.tsv`. The analyzer uses the first sheet
by default. Use `--sheet SHEET_NAME` to select another sheet. It recognizes common
English and Chinese names for date, Campaign, Ad Group, Ad, spend, installs, and D1
retained users. If the export differs, pass a JSON mapping:

```json
{
  "date": "统计日期",
  "campaign": "系列",
  "ad_group": "广告组",
  "ad": "广告",
  "spend": "花费 USD",
  "installs": "安装",
  "retained": "D1 用户"
}
```

The evidence JSON deliberately contains no KPI verdict or action. Ratios are always
recomputed from summed components. Retention windows end on the explicit mature date;
acquisition windows end on the analysis date.

## 2. Apply the decision framework

Read the evidence JSON, confirm the user's KPI card and pacing card, then fill a brief
JSON matching `examples/brief.example.json`. Do not mechanically classify Ads from a
single ratio. Use sample, persistence, trend, maturity, learning stage, recent changes,
and budget impact as required by the Skill.

## 3. Build the Word brief

```bash
python3 scripts/build_brief.py /tmp/brief.json \
  --output ./output/2026-08-25-campaign-triage.docx
```

The renderer enforces the stable tier names and rejects forbidden daily-brief sections
such as Campaign ranking, `核心判断`, and stale named-Ad drilldowns. It uses only three
visual colors and lets tables flow naturally without forced section page breaks.

## Output safety

Write temporary analysis JSON and generated briefs outside the repository. Never add
the user's source workbook or a real advertiser name to examples, fixtures, or assets.