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,150 @@
+# Change response and recovery analysis
+
+Use this reference only when a recent intervention or suspected change point matters:
+budget/bid scaling, rollback, targeting or word-pack changes, creative replacement,
+Ad Group restructuring, a sudden deterioration, a new “black horse,” or a request to
+rescue a previously successful entity.
+
+## 1. Reconstruct the timeline before assigning cause
+
+Create a compact event timeline from the report and intervention log. Split relevant
+history into:
+
+1. **Pre-change control:** the last sufficiently stable configuration and its mature
+   KPI cohorts.
+2. **Transition:** delivery dates whose outcomes are immature or mix old and new
+   configuration effects.
+3. **Post-change:** only cohorts mature enough for each KPI.
+
+Compare like-for-like phases at the lowest trustworthy entity. Show exact dates,
+spend, sample, KPI results, and configuration when known. Rolling 7D/14D windows remain
+useful context, but must not blur a sharp phase break.
+
+Timing is not causality. Use language such as `与变更时间一致` until competing
+explanations are checked. If deterioration began before restructuring, say so: the
+restructure may have amplified or failed to fix the problem, but is not the sole
+demonstrated cause.
+
+## 2. Separate expansion shock from organic deterioration
+
+Call an expansion-related deterioration plausible only when a confirmed budget, bid,
+reach, allocation, or traffic-mix change precedes the mature decline. Observed spend
+alone is not budget history.
+
+- If budget/delivery increased and downstream quality fell after the change, test an
+  expansion or traffic-mix hypothesis.
+- If spend stayed broadly stable while acquisition remained efficient but retention,
+  revenue, or another downstream KPI fell, classify it first as downstream quality
+  deterioration. Investigate audience, inventory, placement, cohort concentration,
+  tracking, and mix shifts; do not label it a budget shock.
+- If acquisition and downstream quality both worsen, keep creative fatigue,
+  targeting saturation, competition, and structural changes in the hypothesis set.
+
+Never invent a causal mechanism from aggregate metrics. State the breakdown needed to
+confirm it, such as placement, device, audience, search term, keyword/match type, geo,
+frequency, or auction diagnostics.
+
+## 3. Decide rollback, containment, or pause
+
+Prefer a controlled rollback/recovery test when all are true:
+
+- a dated intervention plausibly precedes the mature deterioration;
+- a prior configuration is known and operationally restorable;
+- that prior phase has credible evidence, not merely one good day;
+- the rollback does not destroy a currently verified child winner or introduce a
+  broader structural risk.
+
+Rollback is not recovery. If the prior configuration also missed current KPI, label
+the rollback `止损/风险收敛`, not `恢复到有效状态`. Compare it against both the damaged
+phase and the current KPI contract.
+
+During the recovery test, hold other controllable variables fixed. Use the operator's
+configured maturity/sample rule. If none exists, a small run of multiple mature
+cohorts may serve as a provisional checkpoint, followed by a complete recent-window
+validation; clearly label this as a default evidence rule, not a universal truth.
+
+Define exits in advance:
+
+- **Recover:** multiple mature cohorts return to target without a guardrail breach;
+- **Continue cautiously:** directional improvement exists but sample is insufficient;
+- **Escalate/retest:** results remain poor or mixed and a clean hypothesis is testable;
+- **Pause/reduce:** persistent mature failure continues with meaningful exposure and
+  no unresolved data issue.
+
+Avoid daily edits during an observation window unless a hard loss, compliance, or
+tracking guardrail is breached.
+
+## 4. Validate a new or apparent “black horse”
+
+Early averages can be dominated by one cohort. Separate:
+
+- launch/early cohorts;
+- the standout cohort or event;
+- subsequent mature cohorts;
+- immature cohorts, which must not be treated as zeros.
+
+Show how much of the retained outcomes, revenue, or other success measure comes from
+the best day/segment. One strong cohort or one to two good days supports `promising`,
+not `durable winner`. Require the configured minimum sample and multi-cohort
+consistency before scale.
+
+When an early winner weakens but has not accumulated persistent failure, prefer
+hold/protect at a stable test level over immediate scale or pause. Specify the next
+mature checkpoint and the failure condition.
+
+## 5. Rescue a restructured Campaign or Ad Group
+
+Do not decide `replace everything` or `abandon the Campaign` from its aggregate. Build
+a comparison across:
+
+- the prior clean control structure;
+- copied/reused groups;
+- new word packs, audiences, creatives, or match types;
+- current child winners worth protecting.
+
+Measure whether weakness is broad or concentrated and whether the decline started
+before or after each structure change. Historical success is context, but reassess it
+against the current KPI contract; a phase that met acquisition KPI but failed
+downstream quality is not an all-KPI control.
+
+A clean rescue design should:
+
+1. preserve one interpretable control;
+2. isolate one material hypothesis per test group;
+3. reduce duplicate/overlapping audiences, keywords, or creatives where evidence
+   supports overlap risk;
+4. protect verified child winners from being reset or drowned by the test;
+5. use mature, predeclared success and stop conditions.
+
+Do not recommend swapping a whole word pack without keyword/search-term and match-type
+evidence when those are the real levers. Request deeper dimensions only when they can
+change the decision.
+
+## 6. Report the change decision
+
+For an explicitly requested named-Ad follow-up, the optional presentation template is:
+
+```text
+<Ad名称>近7日专项判断
+近7日消耗 | 安装 / 成熟结果 | 主要KPI | 下游KPI | 达标天数
+趋势：<量级、KPI和变更前后走势>
+结论：<保持、回退、低量观察、制作新变体、暂停或扩量判断>
+```
+
+Populate it only from the current source and confirmed context. This is a follow-up
+template, not a standard daily-brief section. Never preserve an example Ad name or
+example metrics as default content.
+
+For each change-related recommendation include:
+
+- entity path and stable ID;
+- declared or inferred change and timestamp;
+- pre-change, transition, and post-change mature evidence;
+- observed fact versus causal hypothesis;
+- action state: rollback/recovery, hold/protect, clean-control retest,
+  pause/reduce, or scale candidate;
+- variables to hold fixed;
+- pacing impact, including the spend gap created by rollback/pause;
+- next mature review point and explicit recover/escalate/exit condition.
+
+Never claim the intervention was executed. This skill remains analysis-only.
@@ -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.
@@ -0,0 +1,58 @@
+# Delivery profile
+
+Use this portable default when the user has not supplied an installation-level
+delivery preference. A user-supplied directory and filename convention always wins.
+
+```yaml
+output_format: docx
+output_directory: ./output
+filename_pattern: "{analysis_date}-campaign-triage.docx"
+chat_behavior: completion_and_file_link_only
+```
+
+Rules:
+
+- `analysis_date` is the delivery/report date analyzed in the brief. Do not substitute
+  the file-generation date when they differ.
+- Create the output directory when absent. Do not overwrite a same-named report until
+  the new DOCX has passed structural and visual verification; build in a temporary
+  path and replace only at final delivery.
+- Preserve the four-section format from `output-standard.md` inside the document.
+- Use a compact professional business-brief design with readable Chinese fonts,
+  deliberate table widths, repeated headers for multi-page tables, and explicit
+  maturity dates.
+- Do not place a `核心判断` summary between the title/date block and section 1.
+- Keep the visual treatment close to a restrained business brief. Do not use
+  full-width section bands, large color blocks, forced section page breaks, or repeated
+  callout boxes; these create excessive pagination when text wraps.
+- Use at most three visible design colors across the document. Prefer one dark blue
+  for headings, one light blue-gray for table headers or thin rules, and neutral gray
+  for secondary text. Do not assign a separate color to every status or section.
+- Separate hierarchy mainly through typography and spacing: numbered section heading,
+  smaller subsection heading, evidence table, and concise labeled interpretation or
+  action. A thin rule beneath a major heading is acceptable; shaded paragraphs are not
+  the default.
+- Keep the action-oriented expression from the accepted direct version. Use short,
+  plain labeled lines such as `待排查`, `趋势`, `结论`, `预算影响`,
+  `继续观察`, `去重原则`, `预算情景`, `3 / 5 / 7天`, `筛选结果`, and `次优参考`
+  where applicable. Bold only the label; do not turn each line into a colored card.
+- Do not include `Campaign层级`, a Campaign ranking table, or `层级判断`. The daily
+  brief is Ad-focused; parent names appear only when needed to identify an Ad.
+- Do not carry a previously discussed named-Ad专项判断 into later daily briefs. Use
+  named-Ad drilldowns only for an explicit follow-up request; retain the structure as
+  a template, never the old entity name or historical values.
+- Do not mechanically insert a separate `结论` paragraph before every table. Let the
+  table present comparable data, then place the nearest decision immediately beside
+  it. In the action section, let the action table lead and follow it with quantified
+  budget impact and observation instructions.
+- Use prose for short conclusions and tables only for genuinely comparable evidence.
+  Keep tables able to flow naturally across pages with repeated headers; do not force
+  a new page merely to keep an entire table or section together.
+- Render every generated DOCX to page images and inspect all pages when a compatible
+  renderer is available. If the renderer is unavailable, perform structural OOXML
+  checks and disclose that visual QA could not run.
+- Do not paste the complete brief into chat after successful file delivery unless the
+  user explicitly asks for an inline copy.
+- Never commit user reports, generated briefs, absolute home-directory paths, account
+  names, or installation-specific KPI into the reusable Skill. Store local overrides
+  outside the repository or in an ignored `delivery-profile.local.md` file.
@@ -0,0 +1,139 @@
+# 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.
@@ -0,0 +1,127 @@
+# Learning-period and stable-period ranking
+
+Apply this two-pool method in every daily brief. The purpose is to prevent fresh tests
+from being judged by mature-entity standards while still pruning obvious failures
+quickly.
+
+## 1. Define age and comparable peers
+
+Use confirmed launch/effective dates when available. Otherwise infer launch from the
+first eligible delivery date and label it as inferred.
+
+- Use calendar age since confirmed launch to detect zero-delivery problems.
+- Use delivered days and KPI-mature cohort days to judge performance.
+- A lagged KPI may have fewer mature cohorts than the entity's calendar age; never
+  count immature values as failures.
+- A major reset to creative, targeting, bid, word pack, or structure may re-enter the
+  affected entity into a learning cohort when it materially changes traffic.
+
+Rank peers only within a comparable scope: same entity level, objective/KPI contract,
+currency, attribution regime, and sufficiently similar launch cohort. Rank sibling Ads
+launched together within their parent before comparing them portfolio-wide.
+
+## 2. Rule one — learning-period pool
+
+Treat a new or materially reset Ad as learning-period through the day-7 checkpoint
+unless the operator configures another window.
+
+### Day 3: early selection
+
+Rank simultaneous tests by this ordered evidence, without inventing a composite score:
+
+1. no hard-guardrail breach;
+2. primary KPI result on mature data;
+3. number of confirmed KPIs meeting target;
+4. distance from target and direction of trend;
+5. mature sample and result concentration;
+6. delivery/budget fill and spend impact.
+
+Actions:
+
+- Confirmed launch with zero spend through three calendar days: label `无投放学习失败`;
+  inspect review/status/bid/audience/data issues and recommend pause/rebuild if no
+  correctable delivery block exists.
+- Spend exists, every mature KPI fails, and sample is adequate: rank last and recommend
+  pause or reduction at day 3. If sample is inadequate, state the exact day-5 sample or
+  spend stop condition rather than treating missing outcomes as proof.
+- Some KPIs meet target and delivery/budget is filling: keep stable through day 5–7;
+  specify which KPI must mature and what failure would stop the test.
+- A peer clearly leads on mature KPIs: label `学习期扩量素材候选`, but do not call it a
+  durable winner yet.
+
+### Day 5: confirmation
+
+- Eliminate persistent bottom-ranked peers when mature evidence and sample support it.
+- Continue mixed but improving or partially compliant entities to day 7 with variables
+  fixed.
+- Promote consistent leaders to a bounded scale-test candidate only when downstream
+  guardrails are mature enough; otherwise keep the candidate label.
+
+### Day 7: graduate or stop
+
+- Graduate to the stable pool when the entity has adequate mature sample and an
+  interpretable run.
+- Mark as a scale candidate when multi-day KPI support, downstream guardrails, and
+  headroom are credible.
+- Pause/reduce or redesign persistent failures. Do not extend `learning` indefinitely
+  to avoid a decision.
+
+At each checkpoint, show rank movement where earlier checkpoints are available.
+
+## 3. Rule two — stable-period pool
+
+Classify entities that graduated from learning or have an established run into one of
+four tiers:
+
+### S-优质
+
+Recent 7D exceeds the confirmed KPI targets with multi-day stability, adequate sample,
+and no severe concentration or recent deterioration. Rank the strongest durable Ads
+first.
+
+### A-稳定
+
+The confirmed KPIs meet target with adequate sample and acceptable multi-day
+consistency. Protect or consider bounded scaling subject to creative age and headroom.
+
+### B-波动待优化
+
+Results fluctuate, only some KPIs meet target, or performance hovers near thresholds,
+but there is still a specific optimization or controlled-retest path. Keep, cap,
+reduce, or test one bounded improvement hypothesis with an exit condition.
+
+### C-劣质
+
+The primary KPI or multiple core KPIs seriously or persistently fail on mature data
+with meaningful exposure, or performance sharply deteriorates without credible
+recovery. Treat these as risk Ads and rank by avoidable loss and confidence for
+pause/reduction review.
+
+Within each tier use the same ordered evidence as the learning pool, then use spend
+impact to prioritize operator attention. Every stable-pool row must include a concrete
+`决定` column.
+
+## 4. Historical winner deterioration and new-material alert
+
+Flag a creative/material alert when an established Ad has a credible strong historical
+control but recent mature performance deteriorates materially and persistently. Show:
+
+- total run age and historically strong window;
+- exact recent 7D versus prior 7D or pre-change evidence;
+- which funnel stage worsened;
+- whether spend, budget, targeting, placement, or audience mix changed;
+- fatigue as a hypothesis only when frequency/CPM/CTR/CVR or creative-age evidence
+  supports it.
+
+Recommend preparing or testing new material when the decline is not explained by data
+lag or an easily reversible traffic change. Protect any still-performing sibling Ads.
+
+## 5. Ranking output invariants
+
+- Show an ordinal rank and the decisive reason; do not present a fake precise score.
+- Rank Ads only; do not output Campaign or Ad Group leaderboards.
+- Show KPI pass count only alongside the primary KPI and hard guardrails; KPI counts
+  alone do not determine quality.
+- State whether budget fill uses configured budget or a delivery proxy.
+- Recompute rank when mature cohorts arrive; do not retroactively treat immature zeros
+  as valid evidence.
@@ -0,0 +1,119 @@
+# Standard daily brief format
+
+Follow this four-section structure exactly. Keep the brief decision-led, but include
+exact dates, mature windows, and enough evidence to audit each action.
+
+## 1. 是否达标
+
+Use compact lines:
+
+```text
+1. 是否达标
+- KPI 1：实际值（达标/未达标；数据日期/成熟 cohort 日期；目标）
+- KPI 2：实际值（达标/未达标；数据日期/成熟 cohort 日期；目标）
+- 日消耗：实际值 / 目标值，差额 xx（达标/未达标；目标类型和范围）
+```
+
+Evaluate at the confirmed portfolio/account scope unless a narrower scope was given.
+Never use the same date automatically for same-day acquisition and lagged retention or
+revenue KPIs. Add at most two short caveats here for material maturity or data issues.
+If KPI Gate B is unsatisfied, state `无法判定` and ask one consolidated question before
+producing action labels.
+
+## 2. 问题分析
+
+Start directly with the Ad-level learning-period and stable-period pools. Do not add a
+Campaign ranking table or `Campaign层级/层级判断` subsection. Campaign and Ad Group may
+appear only in an Ad identity when duplicate names require disambiguation. Keep each
+decision adjacent to its evidence, using a compact labeled line rather than a separate
+visual card.
+
+### 学习期池排名
+
+| Rank | Ad | Age / checkpoint | Spend / budget fill | Mature KPI result | Peer position | Decision |
+|---|---|---|---|---|---|---|---|
+
+Rank comparable new Ads within the same objective and launch cohort. When multiple Ads
+launch together, rank them within that test cohort. Explain day-3 pruning and
+day-5/day-7 observation or promotion decisions.
+
+### 稳定期池排名
+
+| Rank | Tier | Ad | Latest mature day | Recent 7D / prior 7D | KPI pass pattern | Stability / change | Diagnosis | Decision |
+|---|---|---|---|---|---|---|---|
+
+Use exactly these tiers:
+
+- `S-优质`：KPI超额完成且多日稳定。
+- `A-稳定`：KPI达标，样本与持续性足够。
+- `B-波动待优化`：存在波动或部分KPI未达成，但仍有明确优化空间。
+- `C-劣质`：KPI严重或持续不达标，属于风险项。
+
+Rank Ads within and across tiers by primary KPI, number of KPI passes, persistence,
+sample confidence, and spend impact. Every row must include a concrete `决定` such as
+protect, hold, reduce, optimize/retest, pause, or replace creative, together with its
+checkpoint or exit condition when observation continues.
+
+## 3. 建议动作
+
+Group recommendations under only the headings that have qualifying rows:
+
+```text
+3. 建议动作
+- 暂停：<完整层级名称>；原因：<证据>；释放配置预算 xx。
+- 下调：<完整层级名称>；表现波动，建议预算从 xx 下调至 xx；保持至 <成熟日期/样本> 后复查；退出条件：xx。
+- 保持观察：<完整层级名称>；当前通过 xx/总 KPI；保持哪些变量不变；在第 5/7 天或指定成熟日复查。
+- 扩量：<Ad 名称>；近 xx 个成熟日表现很好；建议采用 <可用的受控扩量方式>；回退条件：xx。
+- 补量：距离日消耗目标还差 xx；现有合格扩量容量 xx；仍缺 xx，需新增 Ads <数量或“待测试预算确认”>。
+- 素材预警：<Ad 名称> 已连续跑 xx 天；历史表现好但近期严重下滑；建议验证疲劳/流量变化并准备新素材。
+```
+
+Budget rules:
+
+- `配置预算` comes only from an explicit budget field or operator-provided history.
+- If only spend is available, write `预计减少/释放日消耗约 xx` and label the estimate;
+  never call spend a budget.
+- State an exact reduction only when a configured adjustment rule or credible prior
+  control exists. Otherwise state the direction and the missing value needed.
+- After pause/reduction recommendations, recompute the expected pacing gap.
+- Estimate the number of new Ads only when a standard test budget or a defensible
+  observed test-spend baseline exists; otherwise request that one value.
+
+Every observation action must include a checkpoint and exit condition. A recommendation
+never implies execution.
+
+## 4. 近7天表现好的 Ads（3–5个）
+
+| Rank | Ad（include Campaign > Group） | Stage | Spend / sample | KPI data | Consistency | Why good | Next use |
+|---|---|---|---|---|---|---|---|
+
+Choose three to five Ads only when they genuinely qualify. Rank durable stable Ads
+before learning-period candidates. A learning Ad may appear only when clearly labeled
+`学习期候选`, with its checkpoint and concentration risk. Return one or two, or state
+`暂无合格 Ads`, rather than pad the list with weak traffic.
+
+Explain why each is good using confirmed KPI performance, multi-day consistency,
+sample, trend, and delivery—not adjectives alone. Keep immature outcomes out of the
+negative evidence.
+
+End with `以上均为人工决策建议，未执行任何平台变更。`
+
+## Writing rules
+
+- Use the user's four Chinese section names and order; do not add a separate executive
+  summary or duplicate action table.
+- Do not add a title-page or pre-section `核心判断` paragraph. Begin the report body
+  directly with `1. 是否达标` after the title/date block.
+- Use the exact subsection titles `学习期池排名` and `稳定期池排名`; never prefix them
+  with `规则一` or `规则二`.
+- Do not add a named-Ad `近7日专项判断` section to the standard daily brief. Insights
+  from prior conversation about a specific Ad belong in the reusable follow-up
+  template, not as hardcoded daily-report content, unless the user explicitly asks to
+  include that Ad's drilldown in the report.
+- Use exact calendar dates and exact mature-window ranges.
+- Keep each conclusion or action close to its evidence and avoid repeated colored
+  callout boxes. Prefer direct labels such as `预算影响` and `继续观察` over generic
+  analysis prose.
+- Separate observed facts, inference, and unverified causes.
+- Show numerator/denominator for low-sample or concentration-sensitive ratios.
+- If a subsection is empty, say `无` and why.
@@ -0,0 +1,58 @@
+# 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.
@@ -0,0 +1,56 @@
+# VK optimization guidance
+
+Read this reference when the source is a VK Ads export or the user wants guidance
+that can be applied inside the VK advertising ecosystem.
+
+## Translate evidence into operator levers
+
+Keep the primary diagnosis at Ad level. Use Campaign and Ad Group only to locate the
+Ad, detect shared constraints, or describe the platform lever the operator must use.
+
+Choose the smallest justified lever:
+
+- **Creative control:** pause a persistently poor Ad, protect a mature winner, or copy
+  a proven creative direction into a clean single-variable test. Change one meaningful
+  variable at a time: opening hook, visual sequence, message, format, or CTA.
+- **Learning protection:** do not scale an Ad from one or two good days. Rank new Ads
+  within the same learning pool and apply the 3 / 5 / 7-day checkpoints using mature
+  KPI and adequate sample.
+- **Budget recovery:** after a sharp post-scale decline, recommend a rollback toward
+  the last credible control budget and define a mature recheck window. A rollback is
+  a recovery experiment, not proof that performance has returned.
+- **Audience or word-pack isolation:** when a previously strong combination fails
+  after restructuring, separate creative fatigue from audience/keyword delivery.
+  Recommend a clean control using the prior proven combination when its dated history
+  exists; otherwise label the cause as a hypothesis.
+- **Controlled scaling:** scale durable winners through bounded budget increases or
+  new isolated copies, subject to the user's platform practice and risk limit. Never
+  fill a spend gap by forcing volume into an immature or deteriorating Ad.
+- **Delivery troubleshooting:** zero spend is not automatically poor performance.
+  Ask the operator to inspect VK review/status, bid competitiveness, audience size,
+  schedule, budget availability, and parent-level delivery constraints when the export
+  cannot explain delivery.
+
+## Action wording
+
+Write recommendations so an operator can act without translating vague strategy:
+
+```text
+动作：回退预算并观察
+对象：Creative Alpha（Group One）
+依据：预算提升后，连续3个成熟日的CPI和次留成本同时恶化
+建议：回到最近稳定预算；保持素材、受众和出价不变
+复查：3个成熟日后；若仍未恢复则停止恢复测试
+```
+
+Every action should identify the Ad, evidence window, proposed lever, controlled
+variables, recheck date or sample, and exit condition. If the export has no budget,
+bid, status, audience, or change-history fields, state that limitation instead of
+inventing the exact VK setting.
+
+## Safety boundary
+
+This Skill provides VK-relevant decision support only. Do not claim to have changed
+VK status, budget, bid, audience, word pack, or creative. If the user separately asks
+for execution, require an execution-capable VK workflow and confirm the exact objects
+and mutations immediately before applying them.