Daily-Campaign-Agent/.agents/skills/daily-campaign-triage/references/input-contract.md

# Input and KPI contract

Use this reference when a report is new, its schema is unfamiliar, or KPI maturity
and targets have not already been confirmed.

## 1. Identify the reporting grain

Determine whether each row represents a date, account, Campaign, Ad Group, Ad,
creative, country, placement, or a combination. Preserve the full parent-child path.
Do not aggregate rows across accounts, currencies, timezones, attribution definitions,
or materially different objectives without explicit normalization.

Prefer stable IDs at every available level over display names. If only names exist,
disclose collision and rename risk. Detect whether blank Campaign or Ad Group cells
mean a visually merged/continued parent; forward-fill only inside the current date and
parent block, then reset at boundaries.

Identify parent totals, subtotals, and leaf rows. Aggregate from one consistent grain,
normally the finest trustworthy Ad rows. Never sum a Campaign/Ad Group total together
with its children. Reconcile leaf totals to exported parents when both are available.

## 2. Map fields by meaning, not spelling

Map the available fields to these roles:

- dimensions: date, account, Campaign ID/name, Ad Group ID/name, Ad ID/name, status,
  objective, country, platform;
- delivery: budget, daily spend/pacing target, spend, impressions, reach, clicks,
  installs, conversions, revenue;
- quality/outcomes: retained users, purchases, qualified leads, downstream events;
- ratios: CPM, CPC, CPI, CPA, CTR, CVR, retention, ROAS;
- context: currency, timezone, attribution window, cohort eligibility, data watermark,
  launch date, intervention timestamps, and an intervention/change log.

Column aliases vary by platform and language. Never decide that a similarly named
field is equivalent when its denominator, attribution window, or cohort definition is
unclear. Show the proposed mapping for material fields.

When numerator and denominator are present, compute the aggregate ratio from them and
use the exported ratio only as a cross-check. If only a precomputed ratio is present,
state that weighted aggregation may be impossible.

## 3. Confirm the KPI contract

For each decision-relevant KPI, capture:

| Field | Meaning |
|---|---|
| Role | Primary KPI, secondary KPI, or hard guardrail |
| Formula | Numerator, denominator, and eligible population |
| Direction | Lower-is-better, higher-is-better, or bounded range |
| Target | Business threshold and optional tolerance |
| Scope | Global, account, objective, product, geo, or Campaign-specific |
| Attribution | Click/view window and event definition |
| Maturity lag | When a cohort is complete enough to judge |
| Minimum sample | Spend, clicks, installs, conversions, or eligible cohort |

KPI targets may differ across Campaigns, Ad Groups, or Ads. Apply the narrowest
confirmed target matching the row and display which target was used.

Treat spend/pacing as its own contract:

| Field | Meaning |
|---|---|
| Scope | Portfolio/account, platform, Campaign, or Ad Group |
| Period | Daily, weekly, flight-to-date, or another pacing window |
| Target type | Minimum delivery, desired level, maximum cap, or range |
| Target value | Amount and currency |
| Allocation rule | Whether and where incremental spend may be assigned |

Compute target attainment and gap/overage at the configured scope. A minimum daily
spend goal does not override efficiency or quality guardrails. Report the numerical
shortfall, but do not automatically distribute it to weak Ads.

If any field needed for a verdict is missing, ask a concise question. A useful form is:

> 请确认主要 KPI、目标值和方向；日消耗目标的作用范围；每个滞后指标最晚成熟到哪一天；是否有最低样本门槛或分层目标？

Do not infer a business target from industry benchmarks, historical averages, file
names, source code, or another user's configuration.

## 4. Capture intervention history

When the question involves scaling, sudden deterioration, rollback, a former winner,
or a restructured Campaign, capture each known manual or automated change:

| Field | Meaning |
|---|---|
| Timestamp | Effective time in the reporting timezone |
| Entity path | Campaign, Ad Group, or Ad and stable ID |
| Change type | Budget, bid, targeting, word pack, match type, creative, status, structure, tracking, or platform automation |
| Before / after | Previous and new value or configuration |
| Reason | Operator hypothesis or system trigger, if known |
| Expected maturity | First cohort/date on which the change can be judged |

Keep budget, configured caps, and observed spend distinct. A spend plateau or jump can
suggest a delivery phase, but it does not prove that the budget changed. When the file
contains spend but no budget history, label any inferred phase boundary as an
inference and ask for the change log only if it could materially alter the action.

If there is no formal log, accept dated operator statements as declared context and
mark their provenance. Do not silently turn an approximate recollection into an exact
timestamp.

## 5. Resolve metric-specific mature dates

Let each KPI have its own latest mature date `D_metric`. Examples:

- spend, impressions, and clicks may mature on the latest complete reporting day;
- installs or purchases may require an attribution delay;
- D1 retention for an August 23 cohort cannot be treated as mature until its defined
  next-day observation is complete, so its latest usable cohort may be August 22;
- D7 retention and revenue windows may lag further.

Report `D_metric` beside the KPI. Build recent and prior windows relative to that
metric's mature date. Do not compare an immature value with a mature target.

If maturity cannot be established, present the value as provisional and exclude it
from strong intervention claims.

## 6. Data-quality checks

Before interpretation, check:

- missing or duplicated entity-date rows;
- inconsistent date formats, timezones, currencies, or units;
- blanks confused with zero;
- zero delivery versus absent ingestion;
- totals mixed with detail rows;
- hierarchy blanks incorrectly treated as missing parents or forwarded across blocks;
- parent totals double-counted with Ad Group/Ad detail;
- negative or impossible counts and rates;
- spend with missing outcomes after the expected maturity lag;
- abrupt schema, tracking, attribution, or target changes;
- known intervention dates missing from the export or conflicting with delivery;
- insufficient history for complete 7D/14D comparisons.

Do not silently discard questionable rows. Quantify affected spend and Campaigns when
possible, and decide whether the issue blocks only one KPI or the whole report.