Initial Daily Campaign Agent release

2026-09-16 21:00:13 +08:00
commit 14fc94b3f0
86 changed files with 10766 additions and 0 deletions
@@ -0,0 +1,221 @@
+# Daily campaign triage decision framework
+
+Read this reference before producing a hierarchical intervention and scale queue.
+
+## 1. Construct comparable windows
+
+For each KPI, let `D` be that KPI's latest mature date:
+
+- analysis day: `D`;
+- recent 7D: `D-6..D` using seven mature reporting days;
+- previous 7D: the seven mature reporting days immediately before recent 7D;
+- 14D context: both complete windows together.
+
+If dates are missing, do not quietly substitute seven non-contiguous rows for seven
+calendar/reporting days. Explain the coverage and downgrade confidence. Compare only
+the same metric definition, currency, timezone, attribution window, entity scope, and
+target regime.
+
+For ratio KPIs, aggregate components:
+
+- CTR = total clicks / total impressions
+- CVR = total conversions / configured denominator
+- CPI/CPA = total spend / total attributed outcomes
+- ROAS = total attributed revenue / total spend
+- retention = total retained eligible users / total eligible cohort
+
+Use the user's confirmed formula when it differs.
+
+## 2. Benchmark hierarchy
+
+Use only confirmed business targets for pass/fail decisions. Apply the narrowest
+confirmed target whose scope matches the entity, for example:
+
+1. Ad- or Ad Group-specific target or hard guardrail;
+2. Campaign-specific target or hard guardrail;
+3. confirmed target for the matching product/objective/geo/account;
+4. confirmed account-wide target.
+
+Historical Campaign, peer, or account performance may explain direction and context,
+but is not a business target. Without a confirmed target, label findings
+`无业务 KPI，仅分析趋势` and do not place an entity in intervention or scale buckets
+solely from relative performance.
+
+## 3. Diagnose the hierarchy before choosing an action
+
+Use this sequence when the report contains the dimensions:
+
+1. **Portfolio/account:** quantify daily spend attainment, total risk/opportunity, and
+   which Campaigns concentrate it.
+2. **Campaign:** identify weak, mixed, and strong Campaign aggregates, then measure how
+   performance is distributed across their Ad Groups and Ads.
+3. **Ad Group:** decide whether the issue is shared across material child Ads or
+   concentrated in a few Ads.
+4. **Ad:** classify concrete losers, uncertain Ads, and durable winners.
+
+Campaign averages are routing evidence. They are not sufficient for a Campaign-pause
+recommendation when material child Ads disagree. Quantify concentration with spend,
+outcome, and retained/revenue shares where possible.
+
+Prefer the lowest entity whose evidence supports the proposed lever. If the platform
+cannot change budget or status at Ad level, keep the Ad diagnosis but express the
+human action at the lowest supported parent level and explain the constraint.
+
+## 4. Classify evidence at each relevant entity
+
+Start with the primary KPI and then apply secondary KPI, delivery, and data-quality
+modifiers. Apply these classifications independently to Campaign, Ad Group, and Ad;
+do not inherit a parent's verdict without computing the child's evidence.
+
+### Underperformance
+
+- **Likely one-day noise:** `D` misses target, but recent 7D still meets it or remains
+  stable, same-direction misses are not a majority, and no material risk is worsening.
+- **Mixed/emerging risk:** `D` and recent 7D disagree, multiple KPIs conflict, or the
+  recent window deteriorates without enough consistent evidence.
+- **Persistent underperformance:** recent 7D misses target, at least 4 of 7 mature
+  days miss in the same direction, and previous 7D does not show credible recovery.
+- **Sharp deterioration:** recent 7D materially worsens versus previous 7D while
+  spend is stable or rising, even when the 14D aggregate hides the turn.
+
+`4 of 7` is an evidence-consistency default, not a KPI. Replace it when the user has
+configured a different persistence rule.
+
+### Good performance
+
+- **One-day spike:** `D` looks strong but recent 7D, sample, or concentration does not
+  support it.
+- **Improving candidate:** recent 7D improves and approaches or clears target, but
+  consistency, maturity, or delivery headroom is not proven.
+- **Durable winner:** recent 7D meets target, at least 4 of 7 mature days support it,
+  previous 7D is not contradictory, sample is sufficient, no hard guardrail is
+  breached, and results are not dominated by one event or segment.
+
+## 5. Handle daily spend and pacing
+
+At the configured scope calculate:
+
+- attainment = actual spend / target spend;
+- shortfall = max(target spend - actual spend, 0);
+- overage = max(actual spend - target spend, 0).
+
+Label whether the spend target is a minimum, desired level, cap, or range. When spend
+is below a minimum/desired target, identify how much credible capacity exists among
+durable winners. Never solve a pacing gap by scaling entities that fail efficiency,
+quality, compliance, or data guardrails. If verified winner capacity is smaller than
+the gap, report the unfilled remainder and, when appropriate, propose bounded
+exploration rather than forced scale.
+
+When spend meets or exceeds target, scaling one winner may require reallocating from
+losers rather than increasing portfolio spend. State that distinction.
+
+## 6. Apply decision modifiers
+
+Check every candidate for:
+
+- spend exposure and estimated avoidable loss/opportunity;
+- minimum sample and cohort maturity;
+- launch age and recent budget, bid, creative, targeting, status, or tracking changes;
+- pacing, budget fill, learning limits, and delivery headroom;
+- funnel conflict, such as cheap acquisition with poor retention or weak ROAS;
+- concentration in a day, creative, placement, geo, device, or large revenue event;
+- possible creative fatigue supported by frequency/CPM/CTR/CVR evidence;
+- portfolio effects, shared budgets, audience overlap, or cannibalization;
+- data integrity and attribution lag;
+- prior intervention outcomes when available.
+
+Phrase unsupported causal explanations as hypotheses. A recent intervention normally
+needs time to mature; extreme ongoing exposure can still justify urgent review.
+
+When a recent change, scale event, restructuring, former winner, or rescue question is
+material to the verdict, apply the phase-aware method in
+[change-response.md](change-response.md) before choosing the action.
+
+For the daily brief, do not mix new and mature entities in one leaderboard. Apply the
+two-pool method in [learning-stable-ranking.md](learning-stable-ranking.md).
+
+## 7. Choose the intervention state
+
+Use the smallest state that matches the evidence:
+
+- **Pause/reduce:** persistent mature failure with adequate exposure and no credible
+  recent-change or data-lag explanation.
+- **Rollback/recovery:** deterioration follows a known intervention and a credible
+  prior control can be restored without sacrificing protected winners.
+- **Hold/protect:** evidence is promising or mixed, but changing variables now would
+  destroy the ability to learn; keep the entity stable until the next mature check.
+- **Clean-control retest:** structure or traffic variables are entangled; preserve a
+  control and isolate one hypothesis per test cell.
+- **Scale candidate:** durable winner evidence survives maturity, concentration, and
+  downstream guardrail checks.
+
+Rollback, hold, and retest are explicit actions, not vague observation. State which
+variables stay fixed, the mature observation window, and the exit condition.
+
+### Pause/reduction candidate
+
+Require persistent mature Ad-level underperformance, meaningful spend exposure,
+adequate confirmed sample, and no unresolved attribution, tracking, or recent-change
+explanation. A single bad day or low-sample zero outcome belongs in observation.
+
+When only some Ads fail, protect the good Ads and recommend intervention on the named
+losers. Move to Ad Group only when most material Ads share the problem or the lever is
+available only there.
+
+### Campaign-wide pause candidate
+
+Treat this as exceptional. Require one of:
+
+- broad persistent failure across the Campaign's material Ad Groups and Ads;
+- a Campaign-level structural constraint such as wrong objective/targeting, compliance
+  risk, broken tracking, or unsafe delivery;
+- no durable child winner worth protecting and material ongoing loss.
+
+Show the child-level evidence and spend coverage. Do not recommend Campaign pause from
+the aggregate alone.
+
+### Scale candidate
+
+Require durable mature Ad-level KPI performance, adequate confirmed sample, at least
+the configured consistency rule, no hard downstream guardrail breach, no severe result
+concentration, and plausible delivery headroom. A good day or a good Campaign average
+does not qualify an Ad.
+
+Keep the recommendation platform-neutral. If direct Ad budget scaling is unsupported,
+suggest the applicable controlled lever—parent allocation, bid/target adjustment,
+duplication/test, or creative expansion—without claiming execution. Do not invent a
+scale percentage when no growth rule is configured.
+
+## 8. Prioritize the human queue
+
+Use three explicit judgments instead of a fake precise score:
+
+- **Impact:** avoidable loss/opportunity or share of spend affected.
+- **Confidence:** target validity, maturity, sample, consistency, and data quality.
+- **Urgency:** whether delay increases loss or blocks safe interpretation.
+
+Suggested priorities:
+
+- **P0:** tracking, data, or delivery fault affecting material live spend.
+- **P1:** persistent/high-confidence Ad or Ad Group underperformance, rapid
+  deterioration with material exposure, or broad child-level failure supporting a
+  Campaign review.
+- **P2:** mixed evidence, pending intervention, low sample, or a durable Ad winner
+  that needs an operator decision.
+- **P3:** no material action; summarize only.
+
+Do not recommend a generic pause because one KPI missed. Match the human review to the
+entity and evidence: verify tracking, inspect a breakdown, protect a good Ad,
+cap/reduce/pause a named loser, restore a control, refresh creative, adjust
+targeting/bid, reallocate, or run a controlled scale test. Quantify how a proposed
+pause or rollback changes the pacing gap, and do not nominate an unstable early winner
+to compensate. These remain recommendations, not executed actions.
+
+## 9. Recommended row shape
+
+| Priority | Entity level | Campaign > Ad Group > Ad | State | D vs target | Recent 7D | Previous 7D | Change / pre-post | Spend/sample | Evidence and risk | Human action | Recheck/exit condition |
+|---|---|---|---|---|---|---|---|---|---|---|---|
+
+Each row should make clear what changed, against which confirmed target, over which
+exact mature window, with how much spend/sample, why this entity—not merely its
+parent—owns the action, and why the next review follows.