Open-source SEO, GEO, and marketing skills for AI agents.
feat(google-ads): improve decision quality guidance (#119)
Tong Chenf5275f17ab17
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonindex 1e404416..12c166b4 100644--- a/.claude-plugin/marketplace.json+++ b/.claude-plugin/marketplace.json@@ -5,14 +5,14 @@},"metadata": {"description": "The official ads, analytics, SEO, and GEO plugin from NotFair.",- "version": "0.27.6"+ "version": "0.27.7"},"plugins": [{"name": "notfair","source": "./","description": "Operate Google, Meta, X, and LinkedIn Ads; analyze Search Console and GA4; and run open-source SEO, GEO, and content workflows.",- "version": "0.27.6",+ "version": "0.27.7","author": {"name": "NotFair","url": "https://notfair.co"diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex 76617a3d..f8f2eb0a 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "notfair",- "version": "0.27.6",+ "version": "0.27.7","description": "The official ads, analytics, SEO, and GEO plugin from NotFair. Operate Google, Meta, X, and LinkedIn Ads; analyze Google Search Console and GA4; and run open-source search and content workflows from any compatible agent.","author": {"name": "NotFair",diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.jsonindex 7f2148e3..87d0afb7 100644--- a/.codex-plugin/plugin.json+++ b/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "notfair",- "version": "0.27.6",+ "version": "0.27.7","description": "The official ads, analytics, SEO, and GEO plugin from NotFair.","author": {"name": "NotFair",diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.jsonindex c56b52bd..f9b139c6 100644--- a/.cursor-plugin/plugin.json+++ b/.cursor-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "notfair","displayName": "NotFair",- "version": "0.27.6",+ "version": "0.27.7","description": "Operate Google, Meta, X and LinkedIn Ads, analyze GA4 and Search Console, and run SEO, GEO and content workflows with one NotFair OAuth MCP connection.","author": {"name": "Notfair",diff --git a/CHANGELOG.md b/CHANGELOG.mdindex eca05283..f4250e95 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -9,6 +9,15 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).## [Unreleased]+## [0.27.7] — 2026-09-10++### Changed++- Google Ads recommendations now reconcile conversion definitions, denominators, attribution maturity, and conflicting sources before acting; material decisions include an auditable metric, guardrail, review window, and keep/hold/rollback rule.+- Replaced universal click, conversion, bid-change, and budget-scaling thresholds with account-specific evidence sufficiency and conversion-cycle guidance grounded in current first-party Google Ads documentation.+- Corrected PPC profitability and ROAS formulas, made impression-share and scaling projections explicit scenarios instead of promises, and reinforced that Quality Score is diagnostic rather than a KPI.+- Replaced legacy bidding, account-structure, search-term, Quality Score, and industry-benchmark references that asserted unsupported universal multipliers or model behavior with concise first-party guidance and testable account-specific decisions.+## [0.27.6] — 2026-09-09### Fixeddiff --git a/VERSION b/VERSIONindex c7c49b4b..fb96d142 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-0.27.6+0.27.7diff --git a/gemini-extension.json b/gemini-extension.jsonindex a49b3c8b..76a4e47c 100644--- a/gemini-extension.json+++ b/gemini-extension.json@@ -1,6 +1,6 @@{"name": "notfair",- "version": "0.27.6",+ "version": "0.27.7","description": "Operate ads and analytics, and run open-source SEO, GEO, and content workflows with NotFair.","contextFileName": "AGENTS.md","mcpServers": {diff --git a/google-ads/audit/SKILL.md b/google-ads/audit/SKILL.mdindex a1613415..a33c1554 100644--- a/google-ads/audit/SKILL.md+++ b/google-ads/audit/SKILL.md@@ -28,8 +28,9 @@ These are the handoff to every other ads skill — write them even if the report## Policy freshness check (run first)Read `../shared/policy-registry.json`. For each entry where `last_verified + stale_after_days < today`:-- **High-volatility** → WebSearch the `area` for recent Google Ads changes; compare to `assumption`. If drift, banner the report and suggest registry update.-- **Moderate-volatility** → one-line "may warrant a check" note.+- Any entry without a direct current first-party Google source is a hypothesis, not an audit rule or benchmark. Do not use it for a finding or recommendation without verification.+- **High-volatility** → search the official Google Ads Help, Ads & Commerce blog, or Google Ads developer documentation for the `category`; compare the source with the recorded `rule`. If it drifted, omit the stale rule and banner the limitation.+- **Moderate-volatility** → verify it when it could affect a material finding; otherwise omit it rather than repeating a stale caveat.- **Stable** → skip silently.## Phase 1 — Pull the audit datasetdiff --git a/google-ads/manage/SKILL.md b/google-ads/manage/SKILL.mdindex b5c953ed..fcb048ab 100644--- a/google-ads/manage/SKILL.md+++ b/google-ads/manage/SKILL.md@@ -52,6 +52,9 @@ You decide tool sequencing, GAQL shape, and analytical depth — your judgment iWhat does have to be true on every turn:- Read enough live evidence to support the recommendation; choose tools and query shape from the current connection.+- For any material recommendation, follow `references/decision-quality.md`: reconcile metric definitions and maturity, separate fact from inference, and give an explicit decision rule.+- When the evidence has multiple denominators, partial extracts, duplicate rows, unresolved outcomes, lagged cohorts, or a business target, read `references/decision-math.md` and compute the decision-changing values before choosing an action.+- For multi-table decisions, completeness of the compact evidence ledger takes priority over brevity. Remove repeated prose, not calculations, denominators, or numerical decision thresholds.- Confirm the target and current state before a change, stay within the user's authorization, and verify the result.- Consult the live schema when unfamiliar with a capability. Do not assume defaults, fixed limits, or rollback support.- Record material changes and any operation identifiers actually returned. Use `references/change-tracking.md` when a change merits a later impact review.@@ -64,6 +67,8 @@ These live alongside this skill. Read on demand — not preemptively.| Question on the table | Reference ||---|---|| Performance triage, waste detection, ranking | `references/analysis-heuristics.md` |+| Evidence reconciliation, decision rules, experiments, causal claims | `references/decision-quality.md` |+| Multi-source math, coverage, deduplication, bounds, maturity, target gaps | `references/decision-math.md` + `../shared/ppc-math.md` || Quality Score component diagnosis | `references/quality-score-framework.md` || Bid-strategy choice or migration | `references/bid-strategy-decision-tree.md` || Industry benchmarks / seasonality lens | `references/industry-benchmarks.md` |@@ -110,7 +115,7 @@ After analysis, proactively offer the next skill when the data clearly points th- **CTR persistently below benchmark across 2+ ad groups** → `/google-ads-copy`- **High CTR, low CVR across multiple ad groups** → `/google-ads-landing` (the page is the bottleneck, not the ad)- **No business context, or context >90 days old** → `/google-ads-audit` first-- **Converting search terms not yet keywords (3+ conversions)** → consider adding them through a currently supported capability+- **Repeated, economically valuable search terms not yet keywords** → consider adding them through a currently supported capability after checking intent, coverage, and whether a dedicated keyword would improve control- **Impression-share decline tied to new competitor pressure** → pull `auction_insight_*` resources via GAQL- **Significant structural / bidding change considered** → consider a controlled experiment and verify what the live connection supportsdiff --git a/google-ads/manage/evals/evals.json b/google-ads/manage/evals/evals.jsonindex 7efa25aa..f2fa25ce 100644--- a/google-ads/manage/evals/evals.json+++ b/google-ads/manage/evals/evals.json@@ -31,14 +31,15 @@{"id": 3,"prompt": "I have these keywords and want to optimize bids:\n\n```json\n{\"account_avg_cpa\": 85,\n\"keywords\": [{\"keyword\": \"roof repair austin\", \"bid\": 8.50, \"cpa\": 35, \"conversions\": 22, \"qs\": 9, \"imp_share\": 45}, {\"keyword\": \"roofing contractor\", \"bid\": 12.00, \"cpa\": 140, \"conversions\": 5, \"qs\": 6, \"imp_share\": 30}, {\"keyword\": \"metal roof installation\", \"bid\": 6.00, \"cpa\": 70, \"conversions\": 8, \"qs\": 7, \"imp_share\": 55}, {\"keyword\": \"roof inspection free\", \"bid\": 4.00, \"cpa\": null, \"conversions\": 0, \"clicks\": 45, \"spend\": 180, \"qs\": 4, \"imp_share\": 70}]}\n```",- "expected_output": "Bid optimization recommendations grounded in heuristics: 'roof repair austin' is a star performer (CPA $35 vs $85 avg, QS 9) — increase bid by 15-25% to capture more impression share (currently 45%). 'roofing contractor' has CPA 65% above average — decrease bid or fix QS. 'metal roof installation' is healthy. 'roof inspection free' has $180 spend with 0 conversions and QS 4 — pause or significantly reduce bid.",+ "expected_output": "A decision-ready diagnosis that identifies the apparent winners and risks but does not prescribe bid percentages from incomplete context. It asks for or checks the bidding strategy, target/business economics, conversion definition and lag, and whether impression share is lost to budget or rank. Quality Score is used diagnostically. 'roof inspection free' is a review candidate, but zero conversions alone is not treated as universal proof without maturity and an economic guardrail.","files": [],"expectations": [- "Recommends increasing bid for 'roof repair austin' — references its CPA being well below account average",- "Recommends decreasing bid or pausing 'roofing contractor' — references its CPA being above account average",- "Identifies 'roof inspection free' as waste — $180 spend, 0 conversions, QS 4",- "Bid change recommendations stay within the 25% maximum guardrail",- "References impression share data in the analysis"+ "Identifies 'roof repair austin' as a scale candidate but does not infer that 45% impression share is caused by bid or budget",+ "Identifies 'roofing contractor' as an efficiency concern while distinguishing account average from a business target",+ "Treats 'roof inspection free' as a review candidate and checks conversion maturity and intent before pausing",+ "Does not invent a universal safe bid-change percentage",+ "Requests or checks bidding strategy, conversion definition, target economics, conversion lag, and lost impression share by cause",+ "Uses Quality Score as a diagnostic clue, not a success metric"]},{@@ -134,6 +135,53 @@"Recommends search-term cleanup before scaling","Does not recommend immediate budget increase"]+ },+ {+ "id": 10,+ "prompt": "Google Ads reports 41 conversions at a $58 CPA for the last 14 days, but the CRM shows 8 qualified leads and 2 closed customers. The prior period has 29 Google Ads conversions, but its final three days are missing from the CRM import. Google recommends doubling the budget. Should we do it?",+ "expected_output": "A reconciled decision record that declines an immediate doubling. It distinguishes Google Ads primary conversions from CRM-qualified outcomes, flags incomplete prior-period coverage and conversion maturity, checks which actions drive bidding, and uses qualified economics as the decision source. It may propose fixing/importing deeper outcomes and a staged or experimental budget test with a predeclared metric and guardrail.",+ "files": [+ "google-ads/manage/references/decision-quality.md"+ ],+ "expectations": [+ "Does not compare 41 platform conversions directly with 8 qualified leads as if they share a definition",+ "Flags the incomplete CRM comparison period and conversion lag or import maturity",+ "Checks primary and secondary conversion actions and the campaign goal used for bidding",+ "Does not accept the Google recommendation or double budget automatically",+ "States a primary qualified-business metric, denominator, guardrail, and review condition"+ ]+ },+ {+ "id": 11,+ "prompt": "We changed a Search campaign from lead-form submissions to qualified leads yesterday and Target CPA rose from $90 to $125 today. Please lower the target and rewrite the ads at the same time so performance recovers.",+ "expected_output": "The skill identifies immature post-change data, verifies the qualified-lead action and upload health, and avoids changing both bidding and ads at once. It normally waits for mature conversions over one to two conversion cycles unless a spend guardrail is breached, then proposes one isolated action or experiment with a clear evaluation rule.",+ "files": [+ "google-ads/manage/references/decision-quality.md"+ ],+ "expectations": [+ "Recognizes that one day is too early to judge a conversion-goal change",+ "Checks qualified-lead measurement and primary goal configuration",+ "Does not change the target and ad creative simultaneously",+ "Defines a conversion-cycle-based review point and an early safety guardrail",+ "Separates observed CPA movement from causal explanation"+ ]+ },+ {+ "id": 12,+ "prompt": "A local clinic targets Portland, but 18% of clicks are reported from outside Portland and Search lost impression share is 38%. Quality Score is 5. Should we switch to presence-only targeting, raise the budget 40%, and rewrite every ad?",+ "expected_output": "The skill refuses the bundled prescription. It checks whether location reporting represents user location or location of interest, current advanced location settings, conversion quality by geography, and whether impression share is lost to budget or rank. It treats Quality Score as diagnostic and proposes one reversible change or experiment with a qualified-lead metric and guardrail.",+ "files": [+ "google-ads/manage/references/decision-quality.md",+ "google-ads/manage/references/analysis-heuristics.md"+ ],+ "expectations": [+ "Does not assume all outside-Portland clicks are targeting leakage",+ "Checks presence versus presence-or-interest settings and location report semantics",+ "Separates lost impression share due to budget from rank",+ "Does not optimize directly toward Quality Score",+ "Avoids changing geography, budget, and ads together",+ "Defines the exact first action and how qualified performance will be evaluated"+ ]}]}diff --git a/google-ads/manage/references/analysis-heuristics.md b/google-ads/manage/references/analysis-heuristics.mdindex 4e5a59c3..4a175bd8 100644--- a/google-ads/manage/references/analysis-heuristics.md+++ b/google-ads/manage/references/analysis-heuristics.md@@ -6,7 +6,7 @@ This file is calibration data and guardrails. It is **not** a step-by-step checkBefore reasoning about "good" or "bad" performance, check `{data_dir}/business-context.json.unit_economics`:-- **If `aov_usd` and `profit_margin` exist** — frame everything in dollars (waste = spend on entities with `CPA > Break-Even CPA = AOV × margin`; scaling = positive headroom AND budget-lost-IS > 20%). Read `../../shared/ppc-math.md` for the formulas. Express findings as "saves $X/mo" or "captures $Y/mo headroom" — not "above account average". If `unit_economics.source == "inferred_from_template"`, append a disclaimer noting industry defaults are in use.+- **If verified contribution economics exist** — frame performance against the business's target or break-even CPA/ROAS. Read `../../shared/ppc-math.md` for the formulas. Treat impression share as diagnostic context, not proof that more budget will be profitable. If economics are inferred from a template, label them as estimates and do not authorize a write from them.- **Otherwise** — fall back to account-average comparisons. Pick one framing and stay consistent within a report.Industry calibration lives in `../../shared/industry-templates.json` (read once per audit, cache in memory). Use `business-context.json.industry_template_key` to select the template; otherwise use the account-average fallback.@@ -18,41 +18,40 @@ Before evaluating any keyword's performance, classify it. This prevents pausing| Tier | Definition | Implication ||------|-----------|-------------|| **Tier 1 (Core)** | Keyword directly describes what the business sells | **Never pause on short-window data.** Diagnose root cause and optimize. |-| **Tier 2 (Adjacent)** | Related to the business but not a primary service | Standard heuristics apply after the significance gate below. |+| **Tier 2 (Adjacent)** | Related to the business but not a primary service | Evaluate after the evidence-sufficiency check below. || **Tier 3 (Irrelevant)** | Wrong intent, wrong service, unrelated | Aggressive negativization is appropriate. |Classification signals (without business context): campaign name, ad group name, ad headlines, landing page URL. Matches 2+ signals = Tier 1. Matches 1 = Tier 2. Matches none = Tier 3. With business context, services and high-intent terms in `business-context.json` are the authoritative signal.-When a Tier 1 keyword underperforms, the diagnosis sequence is roughly: enough sample to draw a conclusion → siblings in the same campaign converting → match-type / search-term hygiene → QS subcomponent issue → impression-share / rank context. Recommend optimization, not removal.+When a Tier 1 keyword underperforms, the diagnosis sequence is roughly: measurement and maturity → business value → sibling and search-term comparison → match-type / query hygiene → ad and landing-page match → Quality Score component and impression-share context. Do not remove it solely from a short-window zero, but do not protect a mature, demonstrably uneconomic keyword forever.-## Guardrail: statistical significance gate+## Guardrail: evidence sufficiency-Before any conversion-based decision (pause, bid down, "non-converter" label):+Before a conversion-based decision (pause, bid down, "non-converter" label), check:-1. Compute `expected_conversions = keyword_clicks × account_average_conversion_rate`.-2. If expected conversions < 3, the sample is **insufficient**. Label the entity "Insufficient data" and skip the conversion-based decision. Do not pause.-3. Apply conversion heuristics only when expected conversions ≥ 3 and observed conversions are still 0 or significantly below expected.+1. Is the named conversion action trustworthy and appropriate to the business outcome?+2. Are the date window and comparison complete after conversion lag?+3. Is the baseline comparable by intent, geography, device, network, and campaign role?+4. How large is the spend exposure relative to the target CPA or other business guardrail?+5. Would a plausible late conversion or ordinary variance reverse the decision?++If the answer is unresolved, label the result **insufficient or immature evidence** and set a review condition. `clicks × baseline CVR` can describe expected conversions, but no fixed expected-conversion count is a universal significance test.## Domain facts worth rememberingThese are non-obvious enough that the agent benefits from having them surfaced — they are evidence the AI uses, not rules to apply blindly:-- **Weighted QS by spend, not by keyword count.** A QS-3 keyword burning $2,000/mo matters infinitely more than ten QS-3 keywords burning $5/mo combined.-- **Brand-leakage premium.** When brand campaigns are paused or starved, brand traffic leaks to non-brand campaigns at 5–10× higher CPA. Always check whether brand terms appear in non-brand campaigns' search-term reports.-- **Wasted spend definition.** Spend on Tier 2/3 keywords with 0 conversions and clicks > the significance threshold, plus spend on search terms with low relevance, plus spend on Display Network impressions inside Search-channel campaigns. Tier 1 keywords are optimization opportunities, not waste.-- **Display + Search in one campaign** is structurally broken — Display dilutes Search metrics and burns budget on unintended placements. Flag any Search campaign with `network_settings.target_content_network = TRUE`.-- **Zombie keywords** (0 impressions for 30+ days) clutter reporting and confuse Google's ML — recommend pause.+- **Quality Score is diagnostic, not the objective.** Prioritize high-spend or high-value entities, then use expected CTR, ad relevance, and landing-page experience to locate a likely mismatch. Do not optimize toward the 1–10 score itself.+- **Brand routing can change blended economics.** If brand delivery changes, inspect search terms and campaign routing before attributing a non-brand CPA movement to competition or bidding. Do not assume a universal brand "premium."+- **Wasted spend requires a named counterfactual.** Clearly irrelevant queries can be waste without conversion evidence. Relevant zero-conversion traffic becomes a waste finding only after measurement, maturity, and an economic threshold support that conclusion.+- **Segment network performance.** If a Search campaign also serves on Search Partners or other eligible inventory, compare the segments and conversion quality before recommending exclusion. Mixed inventory is not automatically broken.+- **Non-serving keywords are hygiene, not an ML emergency.** Zero-impression keywords may be paused or removed to reduce operational clutter, but do not claim they confuse bidding without account-specific evidence.- **Counting type matters.** Lead-gen should use `ONE` per click; e-commerce should use `EVERY`. Wrong setting silently inflates or deflates conversions.-- **STOP condition.** If conversion tracking is broken, every downstream optimization is built on lies. Recommend pausing spend until tracking is fixed before any other recommendation.--## Impression Share — interpretive matrix--Rank-lost-IS and budget-lost-IS together tell a story. They're two different problems with two different fixes:+- **STOP condition.** If conversion tracking is broken, stop conversion-led optimization and repair measurement first. Use a protective spend action only when exposure cannot otherwise be bounded.-| | Rank-Lost < 30% | Rank-Lost 30–50% | Rank-Lost > 50% |-|---|---|---|---|-| **Budget-Lost < 20%** | Healthy | QS / bid problem | Quality crisis |-| **Budget-Lost 20–40%** | Budget problem | Mixed (fix quality first) | Structural — too-competitive keywords |-| **Budget-Lost > 40%** | Severe budget gap (high-ROI fix if CPA is good) | Fix rank first, then add budget | Fundamental misalignment — pause and restructure |+## Impression share — interpret the cause, then test the opportunity-This is interpretive context, not a prescription — the right move depends on margin, intent, competitive set, and what the search-term and QS data show. Use the matrix to orient your diagnosis, not to skip it.+- Lost IS (budget) estimates missed eligible impressions attributed to budget; it does not prove the marginal traffic will meet the target CPA/ROAS.+- Lost IS (rank) estimates missed eligible impressions attributed to Ad Rank. Diagnose bid competitiveness, ad/landing-page relevance, and auction context; do not equate it mechanically with Quality Score.+- Low loss on both dimensions can indicate limited eligible demand, but verify targeting, approvals, schedule, and measurement before concluding that the market is exhausted.+- If budget and rank are both constraints, use the business objective and marginal economics to choose the first intervention. Avoid simultaneous changes when an experiment or staged change can identify the driver.diff --git a/google-ads/manage/references/bid-strategy-decision-tree.md b/google-ads/manage/references/bid-strategy-decision-tree.mdindex e78abbfe..eb2c5c37 100644--- a/google-ads/manage/references/bid-strategy-decision-tree.md+++ b/google-ads/manage/references/bid-strategy-decision-tree.md@@ -1,255 +1,59 @@-# Bid Strategy Decision Tree--Systematic framework for selecting, migrating between, and troubleshooting Google Ads bidding strategies. Every recommendation includes transition criteria based on campaign learning status and performance signals.--> **Why automated bidding is strongly preferred (2026):** Google's bidding engine is powered by an LLM-based auction system that evaluates hundreds of real-time signals per auction — device type, precise location, time of day, audience segments, query intent, competitive density, browser, OS, and more. No human bidder can access or process these signals. Manual bidding means forfeiting this advantage entirely, which is why Google's automated strategies consistently outperform manual approaches across virtually all verticals and account sizes. The recommendations below reflect this reality.--> **⚠️ eCPC Deprecation Notice:** Google deprecated Enhanced CPC (eCPC) for new Search campaigns in 2024. Existing campaigns using eCPC may still run, but Google no longer recommends it, and it cannot be selected for new campaigns. All references to eCPC below are for legacy migration purposes only. Do not adopt eCPC for any new campaign.-------## Master Decision Tree--```-START: What is your optimization goal?-|-+-- Goal: Maximize conversions within a budget-| |-| +-- Campaign has exited Learning status AND stable CPA (< 20% variance)-| | --> Target CPA (tCPA)-| |-| +-- Campaign still in Learning or recently launched-| | --> Maximize Conversions (budget-capped) — transition to tCPA once Learning exits-| |-| +-- Very low volume / new campaign with no conversion history-| --> Maximize Conversions (budget-capped) — let the algorithm gather data-|-+-- Goal: Maximize conversion value / ROAS-| |-| +-- Conversion value tracking in place AND campaign exited Learning with sufficient volume-| | --> Target ROAS (tROAS)-| |-| +-- Conversion value tracking in place AND still building volume-| | --> Maximize Conversion Value — transition to tROAS once Learning exits-| |-| +-- No conversion value tracking-| --> Set up value tracking first, use tCPA in the meantime-|-+-- Goal: Drive traffic / brand awareness-| |-| +-- Brand campaign (own brand terms)-| | --> Target Impression Share (target: 95%+ top of page)-| |-| +-- New market / awareness play-| | --> Maximize Clicks (with max CPC cap)-| |-| +-- Competitor conquesting-| --> Target Impression Share (with max CPC cap) or Maximize Conversions (budget-capped)-|-+-- Goal: Testing / new campaign launch- |- +-- Existing conversion data from other campaigns in the account- | --> Maximize Conversions for 2-4 weeks, then transition to tCPA- | (or tCPA directly if account has strong conversion history)- |- +-- No conversion history at all- --> Maximize Conversions (budget-capped) for first 30 days to establish baselines-```-------## Strategy-by-Strategy Reference--### Maximize Conversions--| Attribute | Detail |-|-----------|--------|-| **When to use** | New campaigns, budget-constrained campaigns, campaigns with some conversion history; when the goal is "spend this budget, get as many conversions as possible" |-| **Prerequisites** | Conversion tracking active; defined daily budget you are willing to fully spend |-| **Typical use case** | Campaign launch with $50-200/day budget; seasonal pushes; clearing remaining budget at end of month; replacing Manual CPC for new campaigns |-| **Pros** | Simple setup; spends full budget; good for learning what CPA is achievable; accesses Google's full real-time auction signals from day one |-| **Cons** | No CPA control — will spend entire budget regardless of CPA; can overspend early in the day; may pursue low-quality conversions |-| **Key setting** | Set daily budget carefully — the system WILL spend it all. Optionally set a max CPA bid limit |-| **Learning period** | 1-2 weeks. Do not judge results until 2 full weeks of data |-| **Exit criteria** | Campaign exits Learning status and CPA stabilizes --> move to tCPA |--### Maximize Clicks--| Attribute | Detail |-|-----------|--------|-| **When to use** | Brand awareness campaigns; new market entry; traffic-focused goals; when you have no conversion tracking yet |-| **Prerequisites** | None — works with zero conversion data |-| **Typical use case** | Brand awareness, content promotion, filling top of funnel, market research |-| **Pros** | Maximizes traffic within budget; no conversion tracking needed |-| **Cons** | No conversion optimization; attracts clicks regardless of quality; can burn budget on low-intent queries |-| **Key setting** | ALWAYS set a max CPC bid cap (start at 50% of your target CPC); without it, Google may pay $15+ per click |-| **Exit criteria** | Once conversion tracking is active and sufficient conversions accumulated --> switch to Maximize Conversions (budget-capped) |--### Target CPA (tCPA)--| Attribute | Detail |-|-----------|--------|-| **When to use** | Campaign has exited Learning status; stable CPA over recent weeks; known target CPA |-| **Prerequisites** | Conversion tracking active; campaign exited Learning status; CPA variance < 20% week-over-week |-| **Typical use case** | Mature lead gen, SaaS trials, service bookings, e-commerce with uniform AOV |-| **Pros** | Fully automated bidding optimized for conversions at your target cost; learns from auction signals you cannot access |-| **Cons** | Needs learning period (1-2 weeks); aggressive targets = zero spend; requires sufficient conversion volume |-| **Key settings** | Set target CPA at or slightly above (10-15%) your current average CPA to start |-| **Common pitfalls** | Setting tCPA 30%+ below current average --> campaign stops spending. Setting tCPA too high --> overspending on low-quality conversions |--**tCPA Setup Checklist:**-- [ ] Campaign has exited Learning status (do NOT transition while still in Learning)-- [ ] Set initial tCPA = current average CPA (do NOT set aspirational target)-- [ ] Reduce tCPA by no more than 10-15% per 2-week period-- [ ] Do not make changes during the 1-2 week learning period-- [ ] Ensure daily budget is at least 10x your tCPA target--### Target ROAS (tROAS)--| Attribute | Detail |-|-----------|--------|-| **When to use** | E-commerce with variable order values; sufficient conversion volume with value tracking; known ROAS target |-| **Prerequisites** | Conversion value tracking (revenue per conversion); campaign exited Learning status with stable ROAS; ROAS variance < 25% week-over-week |-| **Typical use case** | E-commerce, multi-product retailers, travel bookings, real estate leads with scored values |-| **Pros** | Optimizes for revenue/profit not just conversion count; smart for variable AOV businesses |-| **Cons** | Needs more data than tCPA; sensitive to conversion value accuracy; can ignore low-value but important conversions |-| **Key setting** | Set target ROAS at or slightly below (10%) your current average ROAS to start |-| **When tROAS beats tCPA** | When conversion values vary 3x+ between transactions (e.g., $50 order vs. $500 order); tCPA would treat these equally, tROAS will prioritize the $500 order |--### Target Impression Share--| Attribute | Detail |-|-----------|--------|-| **When to use** | Brand campaigns (target 95%+ IS); competitive positioning; when visibility matters more than CPA |-| **Prerequisites** | None, but works best with known competitive landscape |-| **Typical use case** | Brand defense, competitor conquesting, product launches |-| **Placement options** | Anywhere on page / Top of page / Absolute top of page |-| **Pros** | Guarantees visibility; protects brand terms from competitors |-| **Cons** | Expensive if targeting high IS on competitive terms; no conversion optimization |-| **Key setting** | Set max CPC cap to prevent runaway costs; target IS: 95% for brand, 50-70% for competitive |--### Enhanced CPC (eCPC) — DEPRECATED--> **⚠️ Legacy strategy.** eCPC was deprecated for new Search campaigns in 2024. It remains available only on existing campaigns that already use it. Do not adopt eCPC for new campaigns. Migrate existing eCPC campaigns to Maximize Conversions or Target CPA.--| Attribute | Detail |-|-----------|--------|-| **When to use** | Legacy only — existing campaigns that have not yet migrated |-| **Prerequisites** | N/A — do not adopt for new campaigns |-| **Typical use case** | Migration candidate: move to Maximize Conversions (budget-capped) or tCPA |-| **Pros** | Slightly more automation than Manual CPC while respecting base bid |-| **Cons** | Deprecated; limited optimization ceiling; Google can raise bids beyond your manual bid; far less effective than tCPA or Maximize Conversions |-| **Key setting** | N/A — focus on migration planning |-| **Exit criteria** | Migrate to Maximize Conversions (budget-capped) or directly to tCPA if conversion volume supports it |--### Manual CPC — NOT RECOMMENDED--> **⚠️ Not recommended for any new campaign.** Manual CPC forfeits access to Google's real-time LLM-based auction signals. Use Maximize Clicks (with CPC cap) for traffic goals or Maximize Conversions (budget-capped) for conversion goals instead.--| Attribute | Detail |-|-----------|--------|-| **When to use** | Extremely rare edge cases only — e.g., regulatory environments requiring fixed bids |-| **Prerequisites** | None — works with zero historical data |-| **Typical use case** | Not recommended for standard use |-| **Pros** | Full control over every keyword bid; no learning period; predictable spend |-| **Cons** | Cannot react to real-time auction signals; misses user-level optimization; time-intensive to manage; consistently underperforms automated strategies |-| **Key setting** | Set bids at keyword level; use ad schedule and device bid adjustments |-| **Exit criteria** | Migrate immediately to Maximize Conversions (budget-capped) or Maximize Clicks (with CPC cap) |-------## Migration Paths--### Standard Migration Ladder--| Step | From | To | Transition Criteria | Timeline |-|------|------|----|---------------------|----------|-| 1 | New campaign | Maximize Conversions (budget-capped) | Conversion tracking active, budget set | Day 1 |-| 2 | Maximize Conversions | Target CPA | Campaign exits Learning status, CPA stabilizes (< 20% variance) | After 2-4+ weeks |-| 3 | Target CPA | Target ROAS | Sufficient conversion volume + value tracking active, conversion values vary 3x+ | When value optimization matters |-| Alt | New campaign (account has conversion history) | Target CPA | Account has strong conversion data from other campaigns | Day 1 (direct) |-| Legacy | eCPC (deprecated) | Maximize Conversions or tCPA | Any time — eCPC should be migrated off | Immediately |--### Migration Safety Rules--| Rule | Why |-|------|-----|-| Allow direct tCPA adoption if the account has conversion history from other campaigns | Google's algorithm can leverage cross-campaign data; rigid step-skipping rules are outdated |-| Never change bid strategy AND campaign settings simultaneously | Impossible to diagnose what caused performance change |-| Allow 2 full weeks after any strategy change before evaluating | Learning period needs time; early data is unreliable |-| Never change bid strategy during seasonal peaks (Black Friday, etc.) | Algorithm relearns during your highest-value period |-| Set initial automated targets at or above current performance | Aggressive targets cause campaigns to stop serving |-| Keep daily budget >= 10x target CPA when using tCPA | Insufficient budget constrains the algorithm and hurts performance |-------## Common Pitfalls by Strategy--| Strategy | Pitfall | Symptom | Fix |-|----------|---------|---------|-----|-| tCPA | Target set 30%+ below current CPA | Spend drops to near zero; few impressions | Raise tCPA to current average CPA, then decrease 10% per 2 weeks |-| tCPA | Daily budget < 5x tCPA target | Inconsistent daily spend; algorithm cannot optimize | Increase budget to 10-15x tCPA target |-| tROAS | Inaccurate conversion values | ROAS looks great but revenue doesn't match | Audit conversion tracking; verify values match actual revenue |-| tROAS | Target set 50%+ above current ROAS | Zero spend, similar to tCPA with too-low target | Set tROAS at 90% of current average, increase 10% per 2 weeks |-| Max Conversions | No budget cap awareness | Entire monthly budget spent in first week | Set daily budget = monthly budget / 30; monitor daily spend |-| Max Conversions | Low-quality conversions | High conversion count but poor lead quality | Add a max CPA bid limit; consider switching to tCPA |-| Max Clicks | No max CPC cap set | Single clicks costing $10-20+ | Always set max CPC cap at 50-75% of target CPC |-| eCPC (legacy) | Still running on campaigns that should migrate | Underperformance vs. automated strategies | Migrate to Maximize Conversions or tCPA |-| Manual CPC (legacy) | Still in use, missing real-time signals | Losing impression share, CPA higher than automated competitors | Migrate to Maximize Conversions (budget-capped) or Maximize Clicks (with CPC cap) |-| Target IS | No max CPC cap on competitive terms | CPC spirals to 3-5x normal | Set max CPC cap; accept lower IS on expensive terms |-------## Portfolio vs. Standard Bid Strategies--| Attribute | Standard (Campaign-level) | Portfolio (Shared across campaigns) |-|-----------|--------------------------|-------------------------------------|-| **Scope** | One campaign | Multiple campaigns share one strategy |-| **When to use** | Campaign has sufficient conversion volume on its own to exit Learning | Individual campaigns lack volume but combined total is enough to exit Learning |-| **Data pooling** | Campaign data only | Pools conversion data across all campaigns in the portfolio |-| **Budget** | Per-campaign budget | Per-campaign budgets still; strategy optimizes across them |-| **Best for** | High-volume campaigns | Low-volume campaigns that share a common goal (same CPA target, same ROAS target) |-| **Avoid when** | N/A | Campaigns have very different CPAs/ROAS targets; different business goals; different conversion types |-| **Example** | Single e-commerce campaign doing 100 conversions/month on tROAS | 5 service-area campaigns each doing 10 conversions/month, combined into a tCPA portfolio at $50 |--### Portfolio Strategy Decision Rule--```-IF single campaign has sufficient volume to exit Learning on its own- --> Use standard (campaign-level) strategy--IF single campaign cannot exit Learning on its own- AND multiple campaigns share the same conversion goal- AND combined volume across those campaigns is sufficient to exit Learning- --> Use portfolio strategy--IF total volume across all candidates is too low to exit Learning even when pooled- --> Use Maximize Conversions (budget-capped) across campaigns until volume builds-```-------## Bid Strategy Performance Evaluation--### What to Measure (By Strategy)--| Strategy | Primary Metric | Secondary Metric | Evaluation Window |-|----------|---------------|-----------------|-------------------|-| Maximize Conversions | CPA trend | Total conversions, budget utilization | Weekly |-| Maximize Clicks | CPC trend, traffic volume | Click quality (bounce rate, time on site) | Weekly |-| tCPA | Actual CPA vs. target CPA | Conversion volume, search impression share | 2-week rolling average |-| tROAS | Actual ROAS vs. target ROAS | Revenue, conversion value | 2-week rolling average |-| Target IS | Actual IS vs. target IS | CPC trend, budget utilization | Weekly |-| eCPC (legacy) | CPA vs. pre-eCPC baseline | Conversion volume change | Bi-weekly (migrate off) |-| Manual CPC (legacy) | CPA or ROAS | Top impression rate, impression share | Weekly (migrate off) |--### When to Intervene--| Signal | Threshold | Action |-|--------|-----------|--------|-| CPA > target by 20%+ for 2+ weeks | Sustained overshoot past learning period | Raise tCPA target by 10%; check for conversion tracking issues |-| Conversion volume drops > 30% | Algorithm may be too constrained | Raise target CPA/lower target ROAS; check for budget limits |-| "Learning" status persists > 3 weeks | Not enough conversion data | Broaden targeting; increase budget; consider less aggressive strategy |-| "Learning limited" status | Budget or targeting too restrictive | Increase budget to 10x+ tCPA; expand audience/keywords |-| CPA < target by 30%+ | Potential to scale | Decrease tCPA by 10% to improve volume; or increase budget |-| Impression share < 50% on brand terms | Competitors bidding on your brand | Switch brand campaign to Target IS at 95% |+# Bid-Strategy Decision Guide++Choose bidding from the advertiser's business goal and trustworthy measurement. Do not use a universal migration ladder, conversion minimum, learning duration, or target adjustment percentage.++## Decision inputs++Before recommending a strategy or target change, establish:++- campaign type and objective;+- primary conversion actions actually used for bidding;+- whether the goal is volume, conversion value/profit, clicks, or visibility;+- target CPA/ROAS or other business constraint and how it was derived;+- budget/capacity ceiling;+- conversion cycle, reporting lag, and recent goal/strategy changes;+- bid-strategy status and relevant simulator or forecast output;+- qualified outcome quality, not only platform conversion count.++If conversion tracking or values are unreliable, fix measurement before conversion-led bidding.++## Goal-to-strategy map++| Business goal | Candidate approach | Preconditions and cautions |+|---|---|---|+| Maximize qualified actions within a fixed budget | Maximize conversions | Primary conversions must represent the desired action; without a target, the strategy seeks volume within budget rather than a guaranteed CPA. |+| Seek qualified actions around a CPA constraint | Target CPA | The target must be economically justified and realistic for the campaign/account context. Evaluate after conversion maturity. |+| Maximize trustworthy conversion value within a fixed budget | Maximize conversion value | Values must be comparable and aligned to the business outcome; raw lead counts with arbitrary values are not sufficient. |+| Seek conversion value around a return constraint | Target ROAS | Requires reliable, differentiated values and a business-derived target. |+| Generate site traffic | CPC-focused bidding or Maximize clicks | Use only when clicks are genuinely the objective or conversion measurement is not the campaign's purpose; set exposure controls appropriate to the account. |+| Seek visibility | Impression-focused strategy such as Target impression share | Define where and why visibility matters, plus a cost ceiling. Do not assume a universal impression-share target, even for brand. |++These are candidates, not automatic answers. Availability and labels vary by campaign type and may change; inspect the live schema and account.++## Changes and learning++- Read the current goal, strategy, target, status, budget, and recent change history before proposing a change.+- Do not change the conversion goal, bid strategy, target, budget, and creative together if you need to know what caused the result.+- For uncertainty, use **Save as experiment** or the supported experiment capability when available.+- After target or conversion-goal changes, assess mature results over the relevant conversion cycle. Google's current guidance says one to two conversion cycles are commonly needed; the account's displayed status and lag take precedence over a fixed number of days.+- Intervene earlier only when a policy, tracking, capacity, or spend guardrail is breached. State that override explicitly.++## Troubleshooting before changing targets++1. Reconcile conversion goals, primary/secondary actions, counting, values, and upload health.+2. Check conversion lag and compare complete equivalent cohorts.+3. Separate budget loss, rank loss, demand, eligibility/policy, query quality, and landing-page constraints.+4. Check recent internal changes and external auction/seasonality evidence.+5. Determine whether the target is constraining delivery or merely correlated with it.+6. Choose one reversible intervention and predeclare the success metric, guardrail, and keep/hold/rollback rule.++## Current Google anchors++Checked 2026-09-09:++- [Align your bid strategy with your campaign goal](https://support.google.com/google-ads/answer/12929373)+- [Your guide to Smart Bidding](https://support.google.com/google-ads/answer/11095984)+- [Changing conversion goals and actions used for Smart Bidding](https://support.google.com/google-ads/answer/14571185)+- [Change how you bid](https://support.google.com/google-ads/answer/6324950)++Google documents product behavior and recommended use; the advertiser's economics and account evidence decide whether a change is good.diff --git a/google-ads/manage/references/campaign-structure-guide.md b/google-ads/manage/references/campaign-structure-guide.mdindex b09a8033..0d38cf27 100644--- a/google-ads/manage/references/campaign-structure-guide.md+++ b/google-ads/manage/references/campaign-structure-guide.md@@ -1,256 +1,56 @@# Campaign Structure Guide-Account structure best practices for Google Ads. Covers campaign organization, ad group design, naming conventions, budget allocation, and settings. Every recommendation includes concrete thresholds and decision criteria.+Structure exists to express different business goals, settings, and intent—not to hit a universal campaign, ad-group, or keyword count.----+## Campaign boundary-## Ad Group Strategy: SKAG vs. STAG vs. Themed+Use a separate campaign when a meaningful campaign-level control must differ, such as:-### Evolution of Ad Group Strategy+- objective or conversion goal;+- budget ownership or business priority;+- geography, language, network, schedule, or policy constraint;+- bidding strategy or profit/CPA target;+- product line or service with materially different economics.-| Era | Strategy | Keywords per Ad Group | Rationale | Current Status |-|-----|----------|-----------------------|-----------|----------------|-| 2012-2017 | **SKAG** (Single Keyword Ad Groups) | 1 | Maximize ad relevance; exact control over which ad shows for which keyword | **Detrimental** — Google's LLM-based bidding and matching systems actively perform worse with single-keyword isolation; theme-based clustering provides the signal density these systems need |-| 2017-2020 | **STAG** (Single Theme Ad Groups) | 3-7 | Group close variants; reduce account complexity while maintaining relevance | **Outdated** — too granular for modern LLM-based bidding; consolidate into themed ad groups of 10-20 keywords |-| 2020-2026+ | **Themed Ad Groups** | 10-20 | Leverage smart bidding; consolidate conversion data; match Google's AI-driven auction system | **Current best practice** |+Do not split solely for cleaner labels when the same settings and outcome apply. Before consolidating or rebuilding, identify what history, eligibility, experiments, reporting, and rollback path would be affected.-### Why SKAGs No Longer Work+## Ad-group boundary-| Problem | Explanation |-|---------|------------|-| Close variants eliminated keyword-level control | Google matches exact match keywords to synonyms, paraphrases, and implied-intent queries regardless of ad group structure |-| Data fragmentation kills smart bidding | A SKAG with 5 conversions/month cannot feed tCPA effectively; the same 50 conversions consolidated into one themed ad group can |-| LLM-based systems need signal density | Google's bidding and matching now use LLM models that require diverse, theme-rich keyword clusters to build accurate intent representations; single-keyword ad groups starve these models of contextual signal |-| Account management overhead | 500 SKAGs = 500 ad groups to manage, each needing unique ads; 25 themed groups covers the same keywords with 95% less maintenance |-| Google rewards consolidation | Google's recommendation engine and smart bidding algorithms perform better with fewer, larger ad groups |+Group keywords and ads around a narrow intent that can be answered by the same offer and landing page. Split when:-### Current Recommendation: Themed Ad Groups+- searchers need a meaningfully different answer or proof;+- ad language or landing destination must differ;+- query routing is producing material mismatch;+- policy or operational ownership requires separation.-| Parameter | Guideline |-|-----------|-----------|-| Keywords per ad group | 10-20 closely themed keywords |-| Theme definition | Keywords should share the same intent AND could be answered by the same landing page |-| Ads per ad group | 2-3 RSAs (Responsive Search Ads) |-| Landing page | 1 primary landing page per ad group (all keywords should be relevant to that page) |-| Match types | Exact + broad match is the standard pairing; phrase and broad now overlap ~100% in many verticals, so phrase match adds minimal incremental value. Use broad match only with smart bidding |+Google currently suggests tightly themed lists and provides 20–30 terms as a structuring tip, but this is not a performance threshold. Intent coherence and message match decide the boundary.-### Theme Grouping Examples+## Restructure diagnosis-| Business | Theme | Keywords in Ad Group | Landing Page |-|----------|-------|---------------------|-------------|-| Plumbing | Emergency repair | emergency plumber, 24 hour plumber, plumber emergency service, urgent plumbing repair, after hours plumber | /emergency-plumbing |-| Plumbing | Drain cleaning | drain cleaning service, clogged drain repair, drain unclogging, sewer line cleaning, blocked drain plumber | /drain-cleaning |-| SaaS | Free trial | [brand] free trial, try [brand] free, [brand] demo, test [brand], [brand] trial account | /free-trial |-| SaaS | Pricing | [brand] pricing, [brand] cost, [brand] plans, how much is [brand], [brand] subscription price | /pricing |-| E-commerce | Running shoes men | men's running shoes, running shoes for men, male running shoes, men's jogging shoes, athletic running shoes men | /mens-running-shoes |+Before changing structure, record:----+1. The observed problem and affected business metric.+2. Evidence that structure—not measurement, query mix, rank, budget, creative, or landing-page friction—is the cause.+3. Current campaign/ad-group settings and dependencies.+4. The proposed mapping from every affected entity to its destination.+5. One primary metric, a guardrail, maturity window, and keep/hold/rollback rule.-## Campaign Organization Patterns+Prefer a controlled experiment where supported. Otherwise stage the smallest reversible slice; do not combine restructure, bidding, budget, goal, and creative changes if attribution matters.-### When to Create Separate Campaigns+## Naming-Create a new campaign when you need any of these to differ:+Names should expose durable operating dimensions, not implementation trivia. A useful pattern is:-| Reason to Split | Example | Why It Requires a Separate Campaign |-|----------------|---------|-------------------------------------|-| **Different daily budgets** | Brand ($50/day) vs. Non-brand ($200/day) | Budget is set at campaign level |-| **Different bid strategies** | Brand (Target IS) vs. Non-brand (tCPA) | Bid strategy is set at campaign level |-| **Different geographic targets** | New York vs. Los Angeles | Location targeting is campaign-level |-| **Different ad schedules** | B2B (Mon-Fri 8am-6pm) vs. B2C (all hours) | Ad schedule is campaign-level |-| **Different networks** | Search Only vs. Search + Display | Network targeting is campaign-level |-| **Different languages** | English vs. Spanish | Language targeting is campaign-level |-| **Fundamentally different services** | Plumbing vs. HVAC | Different landing pages, ads, and conversion goals |+`<objective> | <market> | <product-or-intent> | <optional distinction>`-### When NOT to Split Campaigns+Keep names readable and stable. Put test dates, hypotheses, and owners in labels or intervention records rather than continually renaming entities.-| Scenario | Why Splitting Hurts | Better Approach |-|----------|-------------------|-----------------|-| Splitting by match type (Exact campaign, Phrase campaign, Broad campaign) | Fragments conversion data; smart bidding needs all data in one place. Phrase and broad now overlap ~100% in many verticals, making three-way splits pointless | Mix match types within ad groups; use exact + broad as the standard pairing |-| Splitting every service into its own campaign | 20 campaigns with 5 conversions/month each = too thin for smart bidding | Group related services into one campaign with themed ad groups |-| Splitting brand + non-brand into 10+ campaigns each | Management overhead; inconsistent settings | 1 brand campaign + 2-4 non-brand campaigns organized by service line |-| Splitting by device (mobile campaign, desktop campaign) | Fragments data; smart bidding adjusts bids by device automatically | Use device bid adjustments within one campaign if needed |+## Current Google anchors-**Rule of thumb**: Fewer campaigns with more data each > more campaigns with less data each. Only split when there is a structural reason (budget, bid strategy, geo, schedule).+Checked 2026-09-09:-### Standard Campaign Architecture+- [Organize your account with ad groups](https://support.google.com/google-ads/answer/6372655)+- [About your account organization](https://support.google.com/google-ads/answer/13738436)+- [Manage ad groups for existing campaigns](https://support.google.com/google-ads/answer/2375452)-| Campaign | Purpose | Bid Strategy | Budget Allocation |-|----------|---------|-------------|-------------------|-| **Brand** | Own brand terms | Target IS (95% top of page) | 5-10% of total budget |-| **Non-Brand Core** | Highest-value services/products | tCPA or tROAS | 50-60% of total budget |-| **Non-Brand Secondary** | Lower-priority or newer services | tCPA or Maximize Conversions | 15-20% of total budget |-| **Competitor** | Competitor brand terms (optional) | Target IS (with max CPC cap) or Maximize Conversions (budget-capped) | 5-10% of total budget |-| **Testing** | New keywords, audiences, ad copy tests | Maximize Conversions (budget-capped) or Maximize Clicks (with max CPC cap) | 10-15% of total budget |-| **Remarketing (Display/Search)** | Re-engage past visitors | tCPA | 5-10% of total budget |-------## Naming Conventions--### Convention Format--```-[Network]-[Product/Service]-[Location]-[Audience/Targeting]-[Match/Strategy]-```--### Campaign Naming Examples--| Campaign Name | What It Tells You |-|--------------|-------------------|-| `SRC-Plumbing-Emergency-NYC-tCPA` | Search, Emergency Plumbing, New York City, Target CPA bidding |-| `SRC-Brand-National-TargetIS` | Search, Brand terms, National targeting, Target Impression Share |-| `SRC-HVAC-Install-Chicago-MaxConv` | Search, HVAC Installation, Chicago, Maximize Conversions |-| `DSP-Remarketing-AllServices-National` | Display, Remarketing, All Services, National |-| `SHP-RunningShoes-Mens-US` | Shopping, Running Shoes, Men's, United States |-| `VID-Brand-Awareness-National` | Video (YouTube), Brand Awareness, National |-| `PFM-LeadGen-HomeSvc-TX-tCPA` | Performance Max, Lead Gen, Home Services, Texas, tCPA |--### Network Prefixes--| Prefix | Network |-|--------|---------|-| `SRC` | Search |-| `DSP` | Display |-| `SHP` | Shopping |-| `VID` | Video (YouTube) |-| `PFM` | Performance Max |-| `DSA` | Dynamic Search Ads |-| `APP` | App campaigns |--### Ad Group Naming Examples--| Ad Group Name | Parent Campaign |-|--------------|-----------------|-| `Emergency-Plumber-General` | SRC-Plumbing-Emergency-NYC-tCPA |-| `Emergency-Plumber-24Hour` | SRC-Plumbing-Emergency-NYC-tCPA |-| `Emergency-Plumber-Burst-Pipe` | SRC-Plumbing-Emergency-NYC-tCPA |-| `Brand-Exact` | SRC-Brand-National-TargetIS |-| `Brand-Phrase` | SRC-Brand-National-TargetIS |-| `Competitor-AcmePlumbing` | SRC-Competitor-NYC-ManualCPC |-------## Budget Allocation Framework--### The 70/20/10 Model--| Tier | Allocation | Purpose | Campaign Types |-|------|-----------|---------|----------------|-| **Proven (70%)** | 70% of total budget | Campaigns with established CPA/ROAS that consistently deliver | Brand, core non-brand with 60+ days of data |-| **Testing (20%)** | 20% of total budget | Campaigns being optimized or scaling into new areas | New service lines, new geo expansions, bid strategy tests |-| **Experimental (10%)** | 10% of total budget | High-risk, high-reward experiments | Competitor campaigns, new match types, new networks, DSA |--### Budget Allocation by Campaign Type--| Campaign Type | % of Total Budget | Minimum Daily Budget | Rationale |-|--------------|-------------------|---------------------|-----------|-| Brand | 5-10% | $10/day or 10x brand CPC | Protect brand; high ROAS; don't underfund |-| Non-Brand Core | 50-60% | 10x target CPA | Main revenue driver; needs scale |-| Non-Brand Secondary | 15-20% | 5x target CPA | Growth channel; needs enough to learn |-| Competitor | 5-10% | 5x competitor CPC | Higher CPC; cap spend tightly |-| Testing / Experimental | 10-15% | 10x expected CPC | Enough to gather statistically meaningful data |-| Remarketing | 5-10% | $20/day minimum | High ROI; often underfunded |--### Budget Sufficiency Test--```-Minimum daily budget per campaign = Target CPA x 10--If budget < CPA x 5:- Campaign is critically underfunded. Smart bidding cannot learn.- Action: Increase budget or consolidate into another campaign.--If budget = CPA x 5-10:- Campaign is minimally funded. Results will be inconsistent.- Action: Acceptable for testing phase; increase for scaling.--If budget >= CPA x 10:- Campaign is properly funded. Smart bidding can optimize.- Action: Monitor performance; scale if CPA is at target.--If budget >= CPA x 20:- Campaign has headroom. Smart bidding has room to explore.- Action: Best scenario for automated bidding; expect stable results.-```-------## Ad Group Structure Checklist--| Element | Guideline | Why |-|---------|-----------|-----|-| Keywords per ad group | 10-20 tightly themed | Enough data for smart bidding; tight enough for ad relevance |-| RSAs per ad group | 2-3 | Google recommends 1+ RSA; 2-3 gives testing variety. More than 3 fragments impressions |-| Unique headlines per RSA | 8-15 (Google's maximum) | More headlines = more combinations for Google to test |-| Unique descriptions per RSA | 4 (Google's maximum) | Include keyword, benefits, CTA, and social proof |-| Landing page per ad group | 1 primary URL | All keywords in the group should be relevant to this page |-| Extensions | At minimum: 4 sitelinks, 4 callouts, 1 structured snippet | Extensions increase ad real estate and CTR by 10-20% |--### RSA Best Practices--| Element | Requirements |-|---------|-------------|-| Headline 1 | Must contain the primary keyword or close variant |-| Headline 2 | Unique value proposition or benefit |-| Headline 3 | CTA or trust signal |-| Headlines 4-15 | Variations: numbers, questions, urgency, different benefits, brand name |-| Description 1 | Expand on the value prop; include keyword naturally |-| Description 2 | CTA + differentiator (guarantee, free quote, years in business) |-| Pin sparingly | Only pin Headline 1 (for keyword relevance) and Description 1 (for primary message). Pinning reduces Google's ability to optimize combinations |-------## Campaign Settings Checklist--Review these settings for every new campaign. Incorrect defaults waste budget.--| Setting | Recommended Value | Default (Beware) | Why It Matters |-|---------|-------------------|-------------------|----------------|-| **Networks** | Search only (uncheck Display and Search Partners) | Search + Display + Partners (checked) | Display and Partners have very different performance; run them as separate campaigns |-| **Location targeting** | "Presence: People in or regularly in your targeted locations" | "Presence or interest" (default) | "Interest" shows ads to people searching ABOUT your location but not IN it; wastes budget for local businesses |-| **Location exclusion** | "Presence: People in your excluded locations" | Same as targeting | Ensure excluded locations are actually excluded |-| **Language** | Target your audience's language(s) only | All languages (sometimes default) | Prevent ads showing for queries in languages you don't serve |-| **Ad rotation** | "Optimize: Prefer best performing ads" | Optimize (default is fine) | Let Google's algorithm pick the best ad combination |-| **Start / end dates** | Set end dates for promotions; no end date for evergreen | No end date (default) | Promotional campaigns should auto-stop |-| **Ad schedule** | Set to business hours if B2B; 24/7 if B2C with online conversion | 24/7 (default) | B2B: Why pay for 2am clicks? B2C: online conversions happen at all hours |-| **Device targeting** | All devices (use bid adjustments if needed) | All devices (default is fine) | Smart bidding adjusts by device; manual campaigns may need mobile bid adjustment |-| **Brand exclusions** | Exclude own brand from non-brand campaigns | None (default) | Prevent brand queries from inflating non-brand campaign performance metrics |-| **Dynamic search ads** | Off unless intentionally using DSA. Note: DSA is being superseded by Performance Max, which provides broader automation with asset-group-level control | Sometimes on by default | DSA can match to unexpected pages; use only when deliberately set up. For new campaigns, prefer Performance Max over DSA |--### Location Targeting Detail--| Business Type | Location Setting | Target Radius / Areas |-|--------------|-----------------|----------------------|-| Local service (plumber, dentist) | Presence only | 15-30 mile radius around service area |-| Regional business | Presence only | State or metro area |-| National e-commerce | Presence only | Entire country |-| International | Presence only | Specific countries; separate campaigns per country/language |-| Local + willing to travel | Presence only | Primary area (tight radius) + Secondary area (wider radius, separate campaign with lower bids) |-------## When to Restructure an Account--### Red Flags That Indicate Structural Problems--| Signal | Likely Structural Issue | Restructure Action |-|--------|------------------------|-------------------|-| 50% of campaigns have < 10 conversions/month | Over-segmentation; data too thin for smart bidding | Consolidate campaigns with same goal into fewer campaigns |-| Ad groups have 50+ keywords each | Under-segmentation; ads cannot be relevant to all keywords | Split into themed groups of 10-20 keywords |-| Same keyword appears in 3+ campaigns | Keyword cannibalization; campaigns compete against each other | Deduplicate; assign each keyword to one campaign/ad group |-| Brand and non-brand mixed in same campaign | Inflated performance metrics; budget allocation unclear | Separate brand into its own campaign |-| Display network checked on Search campaigns | Display traffic mixed with search; metrics are muddled | Uncheck Display; run Display as separate campaign if needed |-| Location set to "Presence or interest" for local business | Paying for out-of-area clicks | Change to "Presence" only |-| No negative keyword lists applied | Wasting spend on irrelevant queries | Build and apply universal negative lists |-| Campaign names are inconsistent | Impossible to filter, sort, or analyze by dimension | Rename all campaigns using consistent naming convention |--### Restructure Priority Order--1. **Fix campaign settings** (networks, locations, language) -- immediate impact, zero cost-2. **Separate brand from non-brand** -- clarifies performance data-3. **Build and apply negative keyword lists** -- stops wasted spend within days-4. **Consolidate thin campaigns** -- feeds smart bidding with better data-5. **Reorganize ad groups** -- improves ad relevance and QS-6. **Rewrite ad copy** -- matches new structure with relevant messaging-7. **Update landing pages** -- align with new ad group themes+Re-verify current UI and capability details before a write.diff --git a/google-ads/manage/references/change-tracking.md b/google-ads/manage/references/change-tracking.mdindex 3fa0a592..6bb57a51 100644--- a/google-ads/manage/references/change-tracking.md+++ b/google-ads/manage/references/change-tracking.md@@ -23,8 +23,8 @@ Append to the `changes` array:"note": "Metrics for affected entities at time of change"},"changeIds": ["<changeId(s) returned by write tool>"],- "reviewAfter": "<ISO 8601 -- 7d for bid/keyword changes, 14d for structural>",- "reviewWindow": "<7d or 14d>",+ "reviewAfter": "<ISO 8601 based on conversion maturity and the decision rule>",+ "reviewWindow": "<date range or conversion-cycle rule>","reviewed": false,"reviewResult": null}@@ -33,8 +33,8 @@ Append to the `changes` array:## Rules- **Capture before-metrics** from data already in context. If none available: `"beforeSnapshot": { "metrics": null, "note": "No pre-change metrics" }`.-- **Review windows:** Bid/keyword/negative/budget changes: 7 days. Campaign creates/pauses/restructures/ad copy: 14 days.-- **Tell the user:** "Change logged. Google Ads changes typically take **7 days minimum** to show reliable results (14 days for structural changes like new campaigns or ad copy). I'll check the impact after [reviewAfter date] — you can also ask 'check my changes' anytime."+- **Review windows:** Choose a window from the conversion cycle, reporting lag, expected effect, experiment design, and spend risk. Keep 3/7/14-day checks as operational monitoring when useful, but do not call a winner until the primary outcome is mature.+- **Tell the user:** "Change logged. I’ll review safety and delivery on [early date], then judge the primary outcome after [maturity rule/date]."- **Max 200 entries** (remove oldest reviewed first).- **Group related writes** in one session as a single entry.diff --git a/google-ads/manage/references/daily-ads-operator.md b/google-ads/manage/references/daily-ads-operator.mdindex be051b33..7448bdbe 100644--- a/google-ads/manage/references/daily-ads-operator.md+++ b/google-ads/manage/references/daily-ads-operator.md@@ -70,8 +70,8 @@ Calculate:- Month-to-date spend.- Projected month-end spend at current run rate.- Daily budget vs actual spend yesterday and 7-day average.-- Spike detection: yesterday spend > 150% of 7-day daily average or > 2x daily budget.-- Under-delivery: spend < 50% of budget while lost IS budget is low.+- Spike detection: compare yesterday with the account's recent complete-day distribution, expected pacing, and stored spend guardrail. If no guardrail exists, use a large deviation as a review trigger and show the values rather than declaring a universal threshold.+- Under-delivery: compare actual spend with budget and expected demand, then use lost impression share due to budget versus rank to distinguish budget constraint from eligibility, demand, or relevance. Do not infer a problem from one fixed utilization percentage.Interpretation:diff --git a/google-ads/manage/references/decision-math.md b/google-ads/manage/references/decision-math.mdnew file mode 100644index 00000000..f4015a3e--- /dev/null+++ b/google-ads/manage/references/decision-math.md@@ -0,0 +1,83 @@+# Decision Math for Google Ads++Load this reference when a material recommendation depends on multiple reporting sources, partial extracts, duplicate identifiers, unresolved outcomes, conversion lag, a target CPA/ROAS, or an experiment. Use `../../shared/ppc-math.md` for formulas.++The goal is not a spreadsheet dump. It is a compact derivation ledger containing every value that could change the decision.++## Build the derivation ledger++1. **Name each denominator.** Separate platform conversion events, unique leads, qualified leads, customers, revenue, and retained value. Never compare them as if they were interchangeable.+2. **Reconcile scope.** Show the account/entity, date window, timezone, network, conversion action, source, attribution basis, and maturity status that make each value eligible.+3. **Measure evidence integrity.** When row-level or joined data is supplied, compute extract coverage, join coverage, duplicate rate, deduplicated coverage, timestamp-valid rate, and unresolved rate when each can affect the conclusion. Define duplicate rows as rows beyond the first eligible row per decision identifier unless the source specifies another rule.+4. **Calculate the decision economics.** Compute the relevant raw and cleaned CPA/ROAS, target gap or headroom, spend above target, and any qualified-outcome or contribution-based metric needed for the decision.+5. **Bound uncertainty.** Use best/worst plausible outcomes when unresolved records could cross the target. Use mature cohorts or an explicit completion fraction when recent conversions are incomplete.+6. **Test the counterfactual.** For a performance change, calculate the smallest useful decomposition or control comparison. Do not turn a decomposition into a causal claim.++Do not omit a decisive calculation merely because the directional recommendation already seems obvious. Conversely, omit calculations that cannot change the action, scope, or evaluation rule.++## Minimum coverage by evidence block++Before compressing the analysis, inventory every distinct quantitative block supplied by the user or returned by a relevant read. For each block, either calculate the applicable items below or state briefly why that block cannot affect the decision.++- **Performance rows:** compute the primary outcome rate and CPA/ROAS for every row being compared, plus the total and gap versus target when the rows can be combined.+- **Partial extracts:** compute displayed row count, displayed spend/outcomes, coverage against the full total, and any ineligible or affected share using both the extract and full-total denominators when available.+- **Join or audit ledgers:** compute raw rows, duplicates, unique rows, duplicate rate, eligible join/identifier coverage, and timestamp-valid coverage when supplied. Do not cite an audit table without using its integrity evidence.+- **Grouped themes or segments:** reconcile child sums to the parent total. Name gaps, remainders, or non-additive/overlapping groups instead of silently summing them.+- **Time or maturity cohorts:** compute each comparable cohort's efficiency, the mature weighted baseline, immature projections only when a completion fraction is supplied, and the share of evidence that is mature.+- **Unresolved outcomes:** calculate best/worst plausible bounds and show whether either crosses the target.+- **Experiments or allocation choices:** show attributed performance for context, then separately derive the incremental or break-even threshold that would authorize the decision.++This is a coverage pass, not a requirement to publish a long table. Several calculations may fit on one compact line. What matters is that no quantitative block capable of changing the decision disappears from the record.++When the user asks for a concise answer, compress repeated explanation and packet restatement first. Do not compress away a denominator, reconciliation, bound, target comparison, or calculation required to audit the decision.++## Compact evidence-ledger format++Use a compact structure like this when several sources must be reconciled:++```text+Performance: entity A $spend / outcomes = CPA; entity B ...; target gap ...+Coverage: extract/eligible = rate; ineligible/extract and ineligible/total = rates+Integrity: raw - duplicates = unique; unique/eligible = coverage; valid-time/eligible = rate+Bounds or maturity: confirmed-to-best outcomes => CPA range; mature weighted baseline ...+Decision threshold: keep/test/stop when named metric on named denominator is <= or >= target+```++Use only the lines supported by the evidence. Preserve currency, units, dates, and denominator labels.++## Turn the math into a decision++A complete decision rule states:++- **Act now:** execute, test, hold, or decline, with exact entity and setting scope.+- **Why:** the two or three derived values that actually choose the action.+- **Preconditions:** measurement, maturity, capability, approval, and any evidence-integrity gate.+- **Test design:** one changed lever, named control/comparison, exposure allocation, and downside bound.+- **Primary rule:** metric, denominator, target threshold, and mature evaluation window.+- **Guardrail:** a second metric with a numerical stop threshold when the evidence supports one.+- **Outcomes:** numerical keep, hold/collect-more-data, and rollback branches.++Tie thresholds to the advertiser's stated target, verified contribution economics, or a predeclared baseline. Do not invent universal percentages or sample sizes.++## Evidence must be obtainable++Confirm that the recommended next step can produce the evidence required by the decision rule.++- If an existing report or narrower read resolves the gap, name that exact scope.+- If one side has zero exposure, waiting will not create a comparison. Propose a small reversible exposure-building test with a stable control.+- If the conversion cycle is incomplete, name the maturity date or completion gate rather than saying “wait longer.”+- If measurement is unreliable, repair or bound measurement before conversion-led optimization.+- If a denominator is zero, report the rate as undefined or the cost-per-outcome bound as unbounded; never divide by zero or silently substitute zero.++## Consistency check++Before answering:++1. Recalculate every value that determines the recommendation.+2. Confirm the preferred and rejected options agree with those values.+3. Confirm every percentage names its numerator and denominator.+4. Confirm the target appears in the go/no-go rule.+5. Confirm the test changes one lever and preserves a usable comparison.+6. Confirm the keep/hold/rollback branches are not logically inverted.++If any check fails, correct the decision record before presenting it.diff --git a/google-ads/manage/references/decision-quality.md b/google-ads/manage/references/decision-quality.mdnew file mode 100644index 00000000..abbe15b3--- /dev/null+++ b/google-ads/manage/references/decision-quality.md@@ -0,0 +1,88 @@+# Decision Quality for Google Ads++Use this reference whenever an analysis could change spend, bidding, targeting, conversion goals, campaign structure, or a user's belief about causality. The goal is a decision another operator can audit—not a long report.++## 1. Reconcile the evidence++Before comparing values, write down the smallest sufficient evidence frame:++- account and currency;+- account timezone and complete date window;+- entity scope and network/campaign type;+- metric definition and denominator;+- conversion actions included, primary/secondary status, counting, value, and attribution basis;+- reporting source and conversion maturity;+- relevant recent changes and coverage gaps.++If two sources disagree, do not silently choose one. Name the difference (for example, Google Ads primary conversions versus CRM-qualified leads), quantify overlap or missing coverage if possible, and choose the source that matches the business decision. Keep the other as a diagnostic.++Smallest sufficient does not mean fewest calculations. Before recommending a material change, derive every value that could change the direction or scope of the decision. When the packet or live reads contain partial extracts, duplicate identifiers, unresolved outcomes, lagged cohorts, or a target, use `decision-math.md` and `../../shared/ppc-math.md`. At minimum, check whether the decision needs:++- raw and business-outcome CPA/ROAS on explicitly named denominators;+- extract or join coverage and duplicate rates;+- best/worst bounds for unresolved outcomes;+- conversion-maturity or weighted-cohort adjustment;+- current gap or headroom versus the advertiser's target;+- a cleaned counterfactual or rate-versus-cost decomposition.++Do not calculate everything available. Calculate everything that could reverse the recommendation, change the chosen entity, or alter the go/no-go threshold. Show the inputs and arithmetic compactly enough that another operator can reproduce it.++## 2. Separate the reasoning layers++Use these labels when ambiguity matters:++- **Observed:** the returned evidence directly shows it.+- **Inferred:** the explanation fits the evidence but has alternatives. State what would distinguish them.+- **Causal:** a controlled test or credible design identifies the effect. A before/after chart alone is not enough.++Recommendations and Google optimization scores are inputs, not instructions. Evaluate each against the advertiser's conversion goal, economics, query quality, and constraints before accepting or dismissing it.++## 3. Produce an auditable decision record++For each material recommendation, include:++1. **Decision now:** execute, test, hold, or decline.+2. **Evidence:** the few account-specific facts that drive it.+3. **Uncertainty:** missing, immature, or conflicting evidence.+4. **Exact scope:** entity IDs/names and the current/proposed setting or value.+5. **Evaluation rule:** one primary business metric with its denominator, one guardrail, comparison method, conversion-maturity rule, and a dated or cycle-based review point.+6. **Outcome states:** keep, hold/collect more data, or roll back—with thresholds defined before the change.++Do not invent a universal click, conversion, percentage-change, or duration threshold. Calibrate it to the target CPA/ROAS, baseline rate, plausible effect size, conversion cycle, experiment power, and downside risk.++The exact next step may be a scoped read, reconciliation, or experiment design. Do not force an account mutation when a fact that determines the direction is unresolved.++Check that the proposed evidence can actually be produced. “Wait for a comparison” is not a valid plan when the current configuration gives one side zero exposure or cannot create the needed denominator. In that situation, either name the exact read/configuration that resolves the gap or design the smallest reversible, one-variable test that creates the missing comparison. Keep the current control, define the exposure, and bound downside before launch.++Before sending the answer, recalculate the decisive values and verify that the recommendation, rejected alternatives, and keep/hold/rollback rules all point in the same direction. A numerically inverted rule or a claim that contradicts the stated CPA/ROAS is a failed decision record even if the action sounds cautious.++## 4. Choose observation, staged change, or experiment++- **Observe** when exposure is small, data is immature, or a later conversion could reverse the conclusion.+- **Stage a reversible change** when downside is bounded and operational urgency matters. Change one decision lever, record before/after state, and wait for the defined maturity window.+- **Run an experiment** when the change is material and causality matters. State a business-linked hypothesis, test one variable, preselect one or two success metrics, preserve the base campaign while the test is running, and use the platform result plus mature conversions before choosing a winner.+- **Act protectively** before full maturity only for policy, safety, broken measurement with uncontrolled exposure, obvious irrelevant intent, or a breached spend/business guardrail. Explain why the normal evidence bar is being overridden.++### Common ambiguity gates++- **Geography:** before switching presence settings or excluding an area, distinguish user-location reporting from location-of-interest reporting, confirm the current advanced location option, verify business serviceability, and compare mature qualified outcomes by the relevant location view. An “outside target” percentage alone does not identify waste.+- **Impression share:** a combined or unlabeled lost-impression-share value is not enough for a budget or quality action. Separate loss due to budget from loss due to rank and check eligibility/demand context.+- **Conversion totals:** reconcile `Conversions`, `All conversions`, analytics events, CRM stages, and imported outcomes before choosing the number that bidding or the business should optimize.++## Current first-party Google anchors++Checked 2026-09-09. Re-verify when advice is time-sensitive.++- [Changing conversion goals and actions used for Smart Bidding](https://support.google.com/google-ads/answer/14571185): goal changes can require one to two conversion cycles to learn; avoid judging on immature conversions.+- [About conversion lag reporting](https://support.google.com/google-ads/answer/9347141): recent CPA can look high and ROAS low while conversions are still arriving.+- [About conversion goals](https://support.google.com/google-ads/answer/10995103): primary actions can drive bidding; secondary actions are observation-only unless included through a custom goal.+- [Test with confidence with Experiments](https://support.google.com/google-ads/answer/7281575): set a clear hypothesis, test one variable, preselect success metrics, and avoid contaminating the base.+- [About custom experiments](https://support.google.com/google-ads/answer/10683687): split eligibility does not guarantee equal impressions or spend; allow the trial to stabilize and use the reported comparison.+- [Using Quality Score to guide optimizations](https://support.google.com/google-ads/answer/6167123): Quality Score is a diagnostic tool, not a KPI.+- [Your guide to broad match](https://support.google.com/google-ads/answer/12159290): Google describes Smart Bidding as critical when using broad match; inspect search terms and negatives rather than assuming reach is qualified.+- [About targeting geographic locations](https://support.google.com/google-ads/answer/2453995): the default can include physical presence and location interest; location signals are not perfectly accurate.+- [Enhanced Conversions best practices](https://support.google.com/google-ads/answer/14795081): durable first-party measurement and deeper business outcomes improve optimization inputs.+- [Google Ads bidding and budgeting updates](https://blog.google/products/ads-commerce/bidding-budgeting-google-marketing-live-2026/): Google's current direction uses more of the lead-to-sale journey; beta or announced behavior must still be verified in the live account before relying on it.+- [The Experiments Playbook](https://business.google.com/en-all/think/measurement/experiments-playbook/): link the question to predetermined actions and use power analysis or appropriate statistical support for consequential tests.++These sources describe platform behavior and Google's recommended use. They do not prove that a recommendation is profitable for a particular advertiser; account evidence and business economics still decide that.diff --git a/google-ads/manage/references/industry-benchmarks.md b/google-ads/manage/references/industry-benchmarks.mdindex 50d2cdef..23486e30 100644--- a/google-ads/manage/references/industry-benchmarks.md+++ b/google-ads/manage/references/industry-benchmarks.md@@ -1,223 +1,44 @@-# Google Ads Industry Performance Benchmarks+# External Benchmarks and Forecasts-Industry-specific benchmarks for Google Ads performance evaluation. Data ranges based on widely-published WordStream, Google, and LOCALiQ industry reports (2024-2025 vintage). Use these as diagnostic baselines, not absolute targets.+External averages are context, not a performance target or sufficient evidence for a Google Ads change. CPC, CTR, CVR, CPA, ROAS, impression share, device mix, and seasonality depend on auction, geography, offer, intent, measurement, and business model.-> **Inflation adjustment (2026)**: These benchmarks reflect 2024-2025 data. Google Ads CPCs have been rising 10-20% year-over-year due to increased competition, AI-driven bidding adoption, and SERP layout changes (AI Overviews reducing organic clicks, pushing more demand to paid). When comparing your 2026 performance to these tables, adjust CPC and CPA benchmarks upward by 10-20% to account for market inflation.+## Preferred comparison order----+1. Verified break-even or target economics for the named qualified outcome.+2. The account's mature, like-for-like historical cohort.+3. A concurrent control or Google Ads experiment.+4. Account-specific simulator, planner, and auction-insights output.+5. A current external benchmark with methodology, geography, vertical, date, and sample size.-## Important Caveat+Never inflate an old benchmark by a guessed annual percentage. Never infer that a competitor “stole” traffic from impression share alone. Never use a platform recommendation's projected lift as guaranteed incremental return.-These benchmarks represent **averages across all advertisers**, including poorly optimized accounts. Well-managed accounts typically outperform these benchmarks by **30-50%** on CPA and CTR. If your performance exactly matches these averages, there is significant room for improvement. If your performance is worse than these averages, treat it as an urgent signal.+## Account-specific planning tools----+- **Bid/budget/target simulators:** estimate what might have happened from recent account-specific auction data. Check the conversion definitions and sparse-data limitations; these are estimates, not promises.+- **Performance Planner:** explore spend scenarios using recent auction and seasonality inputs. Select the conversion goal intentionally and verify that its primary actions match the decision.+- **Keyword Planner:** use for demand and cost scenarios, not forecasted profit.+- **Auction insights:** use to describe overlapping eligible auctions and competitive visibility. It does not reveal competitor economics, intent, or causality.-## Search Network Benchmarks by Industry+## If an external benchmark is necessary-> **2026 note**: CPC and CPA figures below are 2024-2025 averages. For 2026 planning, adjust upward by 10-20%. AI Overviews and other SERP layout changes are compressing organic CTR, increasing advertiser demand for paid placements, and driving costs higher across most verticals.+Record:-| Industry | Avg CPC | Avg CTR | Avg Conv Rate | Avg CPA | Notes |-|----------|---------|---------|---------------|---------|-------|-| **Legal** | $6.75 | 4.4% | 7.5% | $90.00 | Highest CPC vertical; personal injury drives the average up |-| **Insurance** | $5.50 | 4.0% | 6.0% | $92.00 | Auto and health insurance are most competitive |-| **Finance & Banking** | $4.50 | 4.2% | 6.5% | $69.00 | Includes credit cards, loans, financial planning |-| **B2B / Industrial** | $3.75 | 3.5% | 5.0% | $75.00 | Long sales cycles; conversion = lead, not sale |-| **SaaS / Technology** | $4.20 | 3.8% | 4.5% | $93.00 | High CPA offset by high LTV; free trial conversions |-| **Healthcare** | $3.25 | 4.5% | 5.5% | $59.00 | Includes dental, dermatology, urgent care |-| **Home Services** | $3.00 | 5.0% | 8.0% | $37.50 | Plumbers, electricians, HVAC; high intent searches |-| **Real Estate** | $2.50 | 4.8% | 3.5% | $71.00 | Low conversion rate; long consideration cycle |-| **Education** | $3.50 | 4.2% | 5.5% | $64.00 | Online courses, degree programs, tutoring |-| **E-commerce** | $1.50 | 4.5% | 4.0% | $37.50 | Broad range; niche e-commerce can be much cheaper |-| **Travel & Hospitality** | $1.75 | 5.5% | 4.5% | $39.00 | Seasonal; OTAs drive up competition |-| **Automotive** | $2.75 | 4.0% | 6.0% | $46.00 | Dealers, parts, service; local intent strong |+- publisher and direct source URL;+- publication/data period;+- geography, network, campaign type, and vertical;+- conversion definition and attribution basis;+- sample size and aggregation method;+- why it is comparable to this account.-### How to Use This Table+Label the result **external directional context**. Do not authorize a bid, budget, pause, or restructure solely from it.-| Your CPA vs. Industry Avg | Diagnosis | Priority Action |-|--------------------------|-----------|-----------------|-| CPA < 50% of industry avg | Excellent — look for scaling opportunities | Increase budget; expand keywords |-| CPA 50-80% of industry avg | Good — optimize for incremental gains | Test new ad copy; refine landing pages |-| CPA 80-120% of industry avg | Average — room for improvement | Audit QS; review search terms; test bid strategies |-| CPA 120-200% of industry avg | Below average — investigate root cause | Check QS (likely < 5); audit keyword relevance; review landing pages |-| CPA > 200% of industry avg | Critical — structural issues likely | Full account audit: conversion tracking, keyword match types, landing pages, ad relevance |+## Current Google anchors----+Checked 2026-09-09:-## Display Network Benchmarks by Industry+- [Estimate results with bid, budget, and target simulators](https://support.google.com/google-ads/answer/2470105)+- [About Performance Planner](https://support.google.com/google-ads/answer/9230124)+- [Use Keyword Planner](https://support.google.com/google-ads/answer/7337243)+- [Use auction insights to compare performance](https://support.google.com/google-ads/answer/2579754)-> **2026 note**: Display CPC figures below are 2024-2025 averages. Display costs have inflated less than Search (5-10% YoY) but still trend upward. Adjust accordingly.--| Industry | Avg CPC (Display) | Avg CTR (Display) | Avg Conv Rate (Display) | Notes |-|----------|-------------------|-------------------|------------------------|-------|-| **Legal** | $0.85 | 0.60% | 1.8% | Display is rarely primary channel for legal |-| **Insurance** | $0.75 | 0.50% | 1.2% | Remarketing performs best |-| **Finance & Banking** | $0.90 | 0.55% | 1.5% | Display for awareness; retarget converters |-| **B2B / Industrial** | $0.70 | 0.40% | 1.0% | Low CTR is normal; focus on impression quality |-| **SaaS / Technology** | $0.65 | 0.45% | 1.2% | Remarketing to free trial abandoners |-| **Healthcare** | $0.55 | 0.65% | 1.5% | Managed placements on health sites perform best |-| **Home Services** | $0.50 | 0.70% | 1.8% | Local display targeting effective |-| **Real Estate** | $0.60 | 0.55% | 0.8% | Low conversion; use for brand building |-| **Education** | $0.45 | 0.60% | 1.3% | Awareness campaigns for enrollment periods |-| **E-commerce** | $0.55 | 0.70% | 1.5% | Dynamic remarketing is the primary use case |-| **Travel & Hospitality** | $0.40 | 0.75% | 1.0% | Inspirational imagery; seasonal targeting |-| **Automotive** | $0.50 | 0.65% | 1.2% | Dealer inventory display ads; local targeting |--**Display baseline rule**: Display CTR is typically 8-12x lower than Search CTR. Display CPC is typically 3-5x lower than Search CPC. Display conversion rates are typically 3-4x lower than Search. This is normal. Display is an awareness and remarketing channel, not a direct response channel.-------## Impression Share Benchmarks--| Campaign Type | Target Impression Share | Acceptable IS | Red Flag IS |-|--------------|----------------------|---------------|-------------|-| **Brand (own brand terms)** | 90-95%+ | 80-90% | < 80% (competitors stealing your brand traffic) |-| **Non-brand competitive** | 40-60% | 25-40% | < 25% (underspending or low QS) |-| **Non-brand long-tail** | 60-80% | 40-60% | < 40% |-| **Competitor terms** | 20-40% | 10-20% | N/A (low IS is expected and acceptable) |-| **Shopping (branded products)** | 70-85% | 50-70% | < 50% |-| **Shopping (generic terms)** | 30-50% | 15-30% | < 15% |--### Impression Share Loss Diagnosis--| IS Loss Type | What It Means | Fix |-|-------------|--------------|-----|-| **Lost IS (Budget)** > 20% | Budget runs out before end of day | Increase daily budget or reduce keyword scope |-| **Lost IS (Budget)** 5-20% | Mild budget constraint | Acceptable if intentional; increase budget for high-ROI campaigns |-| **Lost IS (Rank)** > 30% | Ad Rank too low (QS or bid issue) | Improve QS first (free); for Smart Bidding accounts, loosen target CPA/ROAS to allow higher bids; for manual bidding, increase bids (costs money) |-| **Lost IS (Rank)** 10-30% | Moderate rank issues | Focus QS improvement on highest-volume keywords |-| **Lost IS (Rank)** < 10% | Healthy competitive position | Monitor; no urgent action needed |-------## CTR Benchmarks by Ad Position (Search Network)--| Ad Position | Avg CTR (All Industries) | High-Performing Accounts | Low-Performing Accounts |-|-------------|-------------------------|--------------------------|-------------------------|-| Position 1 (Absolute Top) | 6.0-7.5% | 8.0-12.0% | 3.0-5.0% |-| Position 2 (Top) | 4.0-5.5% | 6.0-8.0% | 2.0-3.5% |-| Position 3 (Top) | 2.5-3.5% | 4.0-5.5% | 1.5-2.0% |-| Position 4+ (Other) | 1.0-2.0% | 2.0-3.0% | 0.5-1.0% |--**Interpretation**: If your ads are in Absolute Top position but CTR is < 5%, your ad copy is underperforming. If your CTR is 8%+ in Absolute Top, your ad copy is strong; focus optimization on CPA and conversion rate instead.--> **SERP layout changes (2026)**: AI Overviews (formerly SGE) now appear on a significant percentage of informational and commercial queries. When AI Overviews are present, they push ads and organic results further down the page, compressing CTR for all ad positions. CTR benchmarks above may overstate expected performance for queries where AI Overviews dominate. Monitor your Absolute Top impression share and CTR trends together — declining CTR with stable impression share may indicate AI Overview interference rather than ad copy issues.-------## Conversion Rate Benchmarks by Landing Page Type--| Landing Page Type | Avg Conv Rate | Top 25% Conv Rate | Top 10% Conv Rate |-|------------------|--------------|-------------------|-------------------|-| Lead gen form (short, < 4 fields) | 5.0% | 8.0% | 12.0%+ |-| Lead gen form (long, 5+ fields) | 3.0% | 5.0% | 8.0% |-| E-commerce product page | 3.5% | 6.0% | 10.0%+ |-| E-commerce category page | 2.0% | 3.5% | 5.5% |-| SaaS free trial page | 4.0% | 7.0% | 11.0% |-| SaaS demo request page | 2.5% | 4.5% | 7.0% |-| Click-to-call (mobile) | 6.0% | 10.0% | 15.0%+ |-| Appointment booking | 4.5% | 7.5% | 12.0% |-------## Seasonal Adjustment Notes by Industry--| Industry | Peak Seasons | CPC Increase During Peak | Recommendation |-|----------|-------------|-------------------------|----------------|-| **E-commerce** | Nov-Dec (holiday), Prime Day (Jul) | +30-60% CPC | Increase budgets 50%+ in Oct; pre-build QS in Sep |-| **Legal** | Jan (New Year resolutions, accidents) | +10-20% CPC | Front-load January budget |-| **Home Services** | Mar-Jun (spring), Sep-Oct (fall prep) | +20-40% CPC | Scale up in Feb; reduce Jan/Dec spend |-| **Travel** | Jan-Feb (booking), Jun-Aug (travel) | +25-45% CPC | Bid on booking intent in Dec; travel intent in May |-| **Education** | Aug-Sep (enrollment), Jan (spring semester) | +20-30% CPC | Campaign launch in Jul and Nov |-| **Finance** | Jan-Apr (tax season), Oct-Dec (planning) | +15-35% CPC | Tax-related campaigns peak Jan-Mar |-| **Healthcare** | Jan (new insurance), Sep-Oct (flu season) | +10-25% CPC | Benefits season in Q4; New Year health in Q1 |-| **Real Estate** | Mar-Jun (spring market) | +20-35% CPC | Scale up in Feb; maintain through Jun |-| **B2B / SaaS** | Jan-Mar (new budgets), Sep-Oct (Q4 planning) | +15-25% CPC | Align campaigns with buyer budget cycles |-| **Insurance** | Oct-Jan (AEP/OEP for health), Mar-May (auto/home) | +30-50% CPC | Open enrollment = highest competition |-| **Automotive** | Mar-May (spring buying), Nov-Dec (year-end deals) | +15-30% CPC | Year-end clearance campaigns |--### Seasonal Budgeting Rule--```-Monthly budget = Annual budget x Seasonal weight factor--Seasonal weight factor:- Peak month: 1.3 - 1.6x (allocate 30-60% more than average month)- Normal month: 0.9 - 1.1x- Off-peak month: 0.5 - 0.8x (reduce spend, not pause)--Example: $120K annual budget, e-commerce- Nov: $120K x 1.5 / 12 = $15,000 (vs. $10K average)- Dec: $120K x 1.6 / 12 = $16,000- Jan: $120K x 0.7 / 12 = $7,000-```-------## Cost-Per-Conversion Benchmarks by Conversion Type--Different conversion types have inherently different values. Compare your CPA to the right benchmark.--| Conversion Type | Typical CPA Range | Top Performers | Notes |-|----------------|------------------|----------------|-------|-| Phone call (from ad) | $15-40 | $8-15 | Highest intent; best for local services |-| Form submission (short form) | $20-60 | $10-25 | 3-5 fields; name, email, phone |-| Form submission (long form) | $35-90 | $15-40 | 6+ fields; qualification questions reduce volume but improve lead quality |-| E-commerce purchase | $25-75 | $10-30 | Highly variable by AOV; $25 CPA on $200 AOV is great, on $30 AOV is terrible |-| Free trial signup | $30-100 | $15-45 | SaaS primary metric; back into this from LTV |-| Demo request | $50-150 | $25-70 | B2B SaaS; lower volume, higher quality than free trial |-| App install | $2-8 | $1-3 | Mobile-first businesses; quality varies widely |-| Newsletter signup | $3-12 | $1-5 | Top of funnel; cheap but low immediate value |-| Click-to-call (mobile) | $10-30 | $5-15 | Mobile-specific; track call duration for quality |-| Store visit | $5-20 | $2-10 | Requires location extensions and sufficient foot traffic data |--### CPA-to-LTV Ratio Guideline--| Ratio (CPA / Customer LTV) | Assessment | Action |-|---------------------------|------------|--------|-| < 10% | Excellent — scale aggressively | Increase budget; expand keywords; test new campaigns |-| 10-20% | Good — healthy acquisition cost | Optimize for incremental gains |-| 20-33% | Acceptable — depends on margins | Ensure margins support this; optimize CPA down |-| 33-50% | Caution — thin margins | Reduce CPA through QS improvement, landing page optimization |-| > 50% | Unsustainable — acquisition cost too high | Pause low-performers; restructure; consider if paid search is the right channel |-------## Mobile vs. Desktop Performance Benchmarks--| Metric | Mobile Avg | Desktop Avg | Ratio | Implications |-|--------|-----------|-------------|-------|-------------|-| CTR | 4.1% | 3.8% | Mobile 8% higher | Mobile gets more clicks due to fewer visible results |-| CPC | 15-25% lower than desktop | Baseline | Mobile cheaper | Opportunity for budget-constrained advertisers |-| Conversion Rate | 2.5-3.5% | 4.0-5.5% | Desktop 40-60% higher | Desktop converts better for complex purchases |-| CPA | 10-30% higher than desktop | Baseline | Mobile more expensive per conversion | Despite cheaper clicks, lower conv rate drives CPA up |-| Bounce Rate | 55-65% | 35-45% | Mobile 50% higher | Mobile pages must load fast and be thumb-friendly |--> **2026 update**: The mobile-desktop conversion rate gap has been narrowing steadily as mobile checkout, autofill, and payment experiences improve (Apple Pay, Google Pay, one-tap checkout). In verticals with strong mobile UX (e-commerce, local services, click-to-call), the gap is now closer to 20-30% rather than the 40-60% shown above. B2B and complex SaaS remain desktop-dominant.--### Device Strategy Decision--> **Smart Bidding note (2026)**: Device bid adjustments are **ignored** by Smart Bidding strategies (tCPA, tROAS, Maximize Conversions, Maximize Conversion Value). Smart Bidding automatically adjusts bids per device based on real-time conversion signals. The recommendations below apply only to Manual CPC or Enhanced CPC campaigns. For Smart Bidding campaigns, optimize the mobile experience (page speed, form simplicity) instead of adjusting bids — the algorithm will find the right bid per device.--| Scenario | Recommended Device Strategy |-|----------|---------------------------|-| E-commerce with mobile-optimized checkout | Bid equally on all devices; mobile can perform well |-| Lead gen with complex forms (5+ fields) | Reduce mobile bid adjustment by 10-20%; or simplify mobile form |-| Click-to-call business (locksmith, towing) | Increase mobile bid adjustment by 20-30%; mobile is primary |-| B2B with long consideration cycle | Reduce mobile bid adjustment by 15-25%; desktop is primary |-| Local services with Google Maps presence | Increase mobile bid adjustment by 10-20%; "near me" is mobile-dominant |-------## Quick Diagnostic: Is My Account Healthy?--Score your account against these benchmarks. 4+ "At or above benchmark" = healthy. 3+ "Below benchmark" = needs immediate work.--| Metric | Check Against | Your Status |-|--------|--------------|-------------|-| Search CTR | Industry avg CTR table | At / Above / Below benchmark |-| Search CPA | Industry avg CPA table | At / Above / Below benchmark |-| Brand IS | 90%+ target | At / Above / Below benchmark |-| Non-brand IS | 40-60% target | At / Above / Below benchmark |-| QS distribution | 30%+ at QS 7+ | At / Above / Below benchmark |-| Conversion rate | Landing page type table | At / Above / Below benchmark |-| Wasted spend (irrelevant search terms) | < 15% of total spend | At / Above / Below benchmark |+These tools remain model-based. Validate material decisions with mature business outcomes and experiments where feasible.diff --git a/google-ads/manage/references/intervention-memory.md b/google-ads/manage/references/intervention-memory.mdindex 48378272..77b05e06 100644--- a/google-ads/manage/references/intervention-memory.md+++ b/google-ads/manage/references/intervention-memory.md@@ -15,10 +15,11 @@ Store or report enough detail for a future 3/7/14-day review:"change_type": "negative_keyword | keyword_add | keyword_pause | bid | budget | ad_copy | landing_page | conversion_tracking | schedule | experiment","summary": "<human summary>","hypothesis": "<what should improve and why>",- "success_metric": "<CPA, CVR, waste spend, lead quality, QS, etc.>",+ "success_metric": "<one business outcome such as qualified CPA, profit, or conversion value per spend>","guardrail_metric": "<what must not degrade>","baseline_window": "<date range>","review_after_days": [3, 7, 14],+ "outcome_maturity_rule": "<conversion-cycle or reporting-completeness rule>","approval_source": "<chat/manual/standing rule>","change_ids": [],"verification": "<verified live state>",@@ -34,7 +35,7 @@ If the environment lacks durable intervention storage, include the record in the## Review protocol-At review time:+The 3/7/14-day points are monitoring defaults, not universal evidence thresholds. At review time:1. Pull before/after metrics for the same scope.2. Normalize to rates where volume changed: CPA, CVR, CTR, CPC, waste-spend share.diff --git a/google-ads/manage/references/quality-score-framework.md b/google-ads/manage/references/quality-score-framework.mdindex 16972c46..925be47f 100644--- a/google-ads/manage/references/quality-score-framework.md+++ b/google-ads/manage/references/quality-score-framework.md@@ -1,74 +1,36 @@-# Quality Score — Mechanics & Diagnostic Reference+# Quality Score Diagnostic-Domain knowledge for diagnosing Quality Score. **This is reference data, not a checklist.** Pull QS component data from this account, identify what's actually broken, and let the data drive the recommendation. Every claim you make about QS has to cite the specific keyword, its components, and its spend (per `../../shared/analysis-principles.md`).+Quality Score is a keyword-level diagnostic, not a KPI, auction input to optimize directly, or reliable formula for predicting CPC savings. Use it to locate relevance problems after business performance and measurement are understood.----+## What Google reports-## Components+Quality Score is shown on a 1–10 scale with three historical comparison components:-Quality Score (1–10, keyword-level) is composed of three sub-components, each rated **Below Average / Average / Above Average**:+- expected click-through rate;+- ad relevance;+- landing-page experience.-| Component | Approx. weight | What Google evaluates |-|-----------|---------------|----------------------|-| **Expected CTR** | ~35–40% | Historical CTR of the keyword, normalized for ad position, extensions, and format |-| **Ad Relevance** | ~20–25% | How closely ad copy matches the keyword's intent and language |-| **Landing Page Experience** | ~35–40% | Page load speed, mobile UX, content relevance, navigation, trust signals |+Each component may be reported as below average, average, or above average relative to other advertisers whose ads showed for the same keyword. Google does not publish fixed component weights or a universal Quality Score-to-CPC multiplier. Do not invent either.-> **Caveat.** Google has never published official QS component weights. The ranges above are estimates from third-party regression studies (notably WordStream and Optmyzr) and may shift over time. Use directionally, not as exact figures.+## Diagnostic sequence-**Key insight:** Landing Page Experience and Expected CTR together account for the majority (~70–80%) of QS. Ad Relevance is the smallest factor — and often the easiest fix.+1. Verify the exact keyword, match type, campaign/ad group, date scope, spend, and business outcome.+2. Pull all three Quality Score components; the headline score alone is insufficient.+3. Read the search terms that actually triggered the keyword. A poor query mix can look like an ad or landing-page problem.+4. Compare ad promise, search intent, and landing-page content. Identify the first broken link in that chain.+5. Check impression-share loss and auction context separately. Quality Score does not explain every rank or delivery change.+6. Recommend the smallest change that addresses the diagnosed component, with a business metric and review rule.----+## Component interpretations-## QS impact on CPC+- **Expected CTR below average:** inspect actual search terms, message specificity, assets, and whether the ad group mixes distinct intents. Do not promise a CPC reduction from a score increase.+- **Ad relevance below average:** align the ad with the user's intent and offer, not merely the literal keyword. Split an ad group only when distinct intents need different ads or landing pages.+- **Landing-page experience below average:** verify message match, mobile usability, speed, navigation, trust, and conversion friction. Hand off to `/google-ads-landing` when page evidence is needed.-Quality Score directly modifies CPC through Ad Rank. Approximate modifiers relative to QS 5 (the neutral baseline):+## Prioritization-| QS | CPC vs. QS 5 | Effective CPC at $2.00 baseline |-|---|---|---|-| 10 | −50% | $1.00 |-| 9 | −44% | $1.12 |-| 8 | −37% | $1.26 |-| 7 | −28% | $1.44 |-| 6 | −17% | $1.66 |-| **5** | **0%** | **$2.00** |-| 4 | +25% | $2.50 |-| 3 | +67% | $3.34 |-| 2 | +150% | $5.00 |-| 1 | +400% | $10.00 |+Prioritize by business exposure: spend, qualified conversion value, target gap, and reachable volume. A low score on a non-serving keyword is usually housekeeping; a middling score on a high-value term may deserve investigation. Never rank work by keyword count alone.-> **Caveat.** These are third-party estimates, not Google-published numbers. Actual modifiers vary by auction, vertical, and account history.+## Current Google anchor-**Rule of thumb:** every 1-point QS increase above 5 saves ~16% on CPC; every 1-point decrease below 5 costs ~50% more. When you cite QS-driven savings, ground them in the specific keyword's spend and current QS — not the rule of thumb alone.--> **Smart Bidding context:** when Smart Bidding (tCPA, tROAS, Maximize Conversions, Maximize Conversion Value) is active, manual bid changes are overridden. Adjust target CPA / target ROAS instead of bid amounts.-------## Component-level diagnosis--Pull QS components for the specific keywords on the table. The data tells you which lever matters here:--- **Expected CTR — Below Average** → the ad isn't earning the clicks Google expected at this position. Likely fixes live in headline relevance, extensions, search-term hygiene, or ad-group tightness. Validate against the actual CTR by impression-location segment (Absolute Top / Top / Other) — average position has been deprecated since September 2019; segment data is the right read.-- **Ad Relevance — Below Average** → the ad copy doesn't match the keyword's intent or vocabulary. Check whether the keyword (or a close variant) appears in any headline, whether the ad group is bloated past 15–20 keywords with mixed intent, and whether the same generic RSA is reused across many ad groups.-- **Landing Page Experience — Below Average** → the page is slow, mismatched, or thin. **Hand off to `/google-ads-landing`** for a structured measurement (PageSpeed Insights, message-match, mobile UX, trust signals, form friction). That skill produces evidence-backed dimensional scores; don't try to second-guess it from GAQL alone.-------## Close-variant context--Google applies close variants to all match types — misspellings, singular/plural, stemming, abbreviations, accents, implied words, synonyms, paraphrases, and (for Broad) same-intent expansions. This means ad copy needs to cover the broader intent space, not just the literal keyword text. When diagnosing low Ad Relevance, pull the search-term report alongside the keyword and ad copy — the gap often shows up there.--See `search-term-analysis-guide.md` for the full close-variant reference and the negative-keyword precision caveats under Broad / Search Themes / PMax.-------## Health-check questions--When evaluating QS at the account level, the data you actually want to look at:--- What share of impression-volume sits at QS 7+, QS 5–6, and QS 1–4? Concentration of spend on QS ≤ 4 is where the money leaks.-- Which 10 keywords have the largest spend × (5 − QS) gap? That's the prioritized fix list — not a generic "raise QS everywhere".-- Is one QS component dragging across many keywords (e.g., Landing Page Experience: Below Average on 60% of keywords)? That's a structural problem, not a per-keyword one.--Answer these from this account's data and let the answers shape the recommendation. The hierarchy of impact on overall account performance is roughly Landing Page Experience > Expected CTR > Ad Relevance — but spend-weighted is what matters, not the percentage of keywords.+Checked 2026-09-09: [Using Quality Score to guide optimizations](https://support.google.com/google-ads/answer/6167123) explicitly describes Quality Score as a diagnostic tool, not a KPI. Re-verify before asserting current platform behavior.diff --git a/google-ads/manage/references/repeatable-optimization-loops.md b/google-ads/manage/references/repeatable-optimization-loops.mdindex 2831ccd9..5edb8486 100644--- a/google-ads/manage/references/repeatable-optimization-loops.md+++ b/google-ads/manage/references/repeatable-optimization-loops.md@@ -31,7 +31,7 @@ Report in this order:### Decision rules-- Thin data: if the day has <3 clicks or expected conversions <1, do not overfit. Say what you are watching for.+- Thin or immature data: do not overfit a recent day. Compare with a complete baseline, account for conversion lag, and say what evidence or business guardrail will trigger the next review.- Query quality problem: propose negatives only for clearly irrelevant terms or repeated expensive bad patterns.- Clean traffic but no conversions: check landing page / form / tracking before touching bids.- Rank-limited and far under budget: prioritize ad relevance, Quality Score, landing-page message match, and bid competitiveness; do not recommend more budget.diff --git a/google-ads/manage/references/search-term-analysis-guide.md b/google-ads/manage/references/search-term-analysis-guide.mdindex fb921dca..90a0749c 100644--- a/google-ads/manage/references/search-term-analysis-guide.md+++ b/google-ads/manage/references/search-term-analysis-guide.md@@ -1,283 +1,67 @@-# Search Term Analysis Guide+# Search-Term Analysis Guide-Systematic framework for interpreting search term reports, mining keywords, building negative keyword lists, and maximizing paid search relevance. Every recommendation includes concrete thresholds and actionable workflows.+Use the search terms report to understand the queries that actually triggered ads. Search terms, positive keywords, and negative keywords behave differently; verify current match behavior and live account scope before mutating.----+## Evidence frame-## Match Type Behavior Reference+For the chosen complete window, retain:-Understanding what Google actually matches to each match type is the foundation of search term analysis.+- search term, campaign, ad group, and matched keyword where available;+- match type and network/campaign type;+- cost, clicks, impressions, primary conversions, qualified outcomes, and value;+- account currency, timezone, conversion definition, attribution basis, and maturity;+- existing positives, negatives, brand exclusions, and relevant recent changes.-### Match Type Definitions (Current Behavior, 2025-2026)+Search-term reporting may not expose every query. State coverage limits instead of treating the table as the full universe.-| Match Type | Syntax | What It Matches | Example Keyword | Example Matched Queries |-|-----------|--------|----------------|-----------------|------------------------|-| **Broad Match** | `keyword` | Themes, intent, related concepts; uses AI to determine relevance | `plumber services` | "plumber near me", "fix leaky faucet", "emergency pipe repair", "plumbing contractor reviews" |-| **Phrase Match** | `"keyword"` | Queries that include the meaning of the keyword; word order matters for meaning. In practice, semantic overlap with Broad match is nearly complete in most verticals (2025-2026). | `"plumber services"` | "plumber services near me", "affordable plumber services in austin", "residential plumber services" |-| **Exact Match** | `[keyword]` | Queries that match the exact meaning including close variants | `[plumber services]` | "plumber services", "plumber service", "plumbing services", "services plumber" |+## Aggregate before acting-> **Note (2026):** Phrase and Broad match overlap is nearly 100% in many verticals. Running both on the same keyword is redundant. In most cases, choose one: Broad with Smart Bidding for maximum reach, or Exact for maximum control. Adding Phrase match alongside Broad rarely changes which queries you match.+Analyze both individual queries and repeated 1-, 2-, and 3-gram intent patterns. Aggregate cost and qualified outcomes, retain example queries, and identify the campaigns/ad groups where each pattern appears.-### Close Variants (All Match Types)+Classify into:-Google applies close variants to ALL match types. These include:+1. **Clear exclusion candidate:** the verified business does not serve the intent, geography, audience, or offer.+2. **Keyword/control candidate:** repeated valuable intent where a dedicated keyword could improve routing, ad/landing-page match, or reporting.+3. **Routing conflict:** the same intent lands in multiple ad groups or campaigns with meaningfully different outcomes.+4. **Ad/landing-page mismatch:** relevant query, but the promise or destination fails the intent.+5. **Watch:** evidence is relevant but immature, incomplete, or economically reversible.-| Close Variant Type | Example Keyword | Matched Query | Risk Level |-|-------------------|-----------------|---------------|------------|-| Misspellings | `plumber` | "plumer", "plummber" | Low — usually helpful |-| Singular / Plural | `running shoe` | "running shoes" | Low — usually helpful |-| Stemming | `running` | "run", "runner" | Low-Medium — check intent |-| Abbreviations | `california` | "CA", "calif" | Low — usually helpful |-| Accents | `cafe` | "cafe" | Low — usually helpful |-| Implied words | `daytime tv` | "tv shows during the day" | Medium — may shift intent |-| Synonyms | `cheap hotels` | "affordable hotels", "budget hotels" | Medium — check relevance |-| Paraphrases | `how to fix a faucet` | "faucet repair steps" | Medium — usually OK |-| **Same intent (broad)** | `plumber services` | "fix leaky pipe" | **High — can be very far from keyword** |+## Negative-keyword safety-### Close Variant Gotchas+- Confirm the business truly does not want the intent. Words such as “free,” “course,” or “jobs” are not universally irrelevant.+- Choose account, list, campaign, or ad-group scope deliberately.+- Choose negative broad, phrase, or exact behavior deliberately; negative matching does not behave like positive close variants.+- Check conflicts against protected brand/core terms, converting queries, existing positives, and other campaigns before applying.+- Preview exact targets and counts, get approval, execute through the safe pattern, and read back live state.-| Gotcha | Example | Impact | Mitigation |-|--------|---------|--------|------------|-| Google matches exact match to synonyms you didn't intend | `[luxury hotel]` matches "5 star resort" | May not match your landing page | Add exact negative `[5 star resort]` if landing page is hotel-specific |-| Broad match picks up tangentially related queries | `plumber` matches "DIY pipe repair youtube" | Wasted spend on informational, non-commercial queries | Add negative keywords: "DIY", "youtube", "how to" |-| Phrase match reorders words when Google determines same meaning | `"new york plumber"` matches "plumber in new york" | Usually fine, but check | Monitor search terms weekly |-| Exact match singular/plural shifts intent | `[glass]` matches "glasses" (eyewear vs. material) | Completely different intent | Add negative `[glasses]` if selling glass material |+Clearly irrelevant intent can justify an exclusion without waiting for conversions. A relevant zero-conversion query needs trustworthy measurement, mature data, and a business guardrail; no universal click count makes it waste.----+## Match-type decisions-## Relevance Scoring Framework+Exact, phrase, and broad describe progressively wider semantic reach. Their performance cannot be compared fairly without reconciling query mix, bidding, routing, goals, and maturity.-Score every search term on a 1-5 scale to prioritize actions.+Google's current guidance says broad match should be used with Smart Bidding. Treat that as a testable platform recommendation, not proof of fit. Confirm primary conversion quality, sufficient downside budget, and search-term controls; use an experiment for a material migration.-| Score | Label | Definition | Example (for keyword "emergency plumber") | Action |-|-------|-------|------------|-------------------------------------------|--------|-| **5** | Perfect Match | Query exactly matches keyword intent and is high-converting | "emergency plumber near me" | Add as keyword if not already targeted |-| **4** | Strong Relevant | Related to keyword, clear commercial intent, likely converter | "24 hour plumber service" | Add as keyword if 2+ conversions |-| **3** | Moderately Relevant | Related but broader intent or lower purchase signals | "plumber cost estimate" | Monitor; add as keyword if converting consistently |-| **2** | Weakly Relevant | Tangentially related; unlikely to convert at acceptable CPA | "plumber salary", "plumber apprenticeship" | Add as negative if 10+ clicks with zero conversions |-| **1** | Irrelevant | No relation to business or search intent | "mario plumber game", "plumber meme" | Add as negative immediately |+Adding a search term as a keyword is useful only when it creates control or learning value. A fixed number of conversions is not a reason by itself, and an exact keyword does not guarantee exclusive routing.----+## Output-## Search Term Mining Workflow+Return:-### Decision Rules+- scope and coverage;+- top patterns by business exposure;+- proposed exclusions, keyword/routing candidates, and watches;+- conflicts or prerequisites;+- exact approved-action queue;+- primary qualified metric, denominator, guardrail, and maturity/review rule.-```-FOR EACH search term in the report:-|-+-- Has 3+ conversions at acceptable CPA?-| YES --> Add as keyword (exact match) in the most relevant ad group-| NO --> Continue evaluation-|-+-- Has 10+ clicks with 0 conversions?-| YES --> Add as negative keyword (exact negative if one bad term;-| phrase negative if a pattern)-| NO --> Continue evaluation-|-+-- Has 50+ impressions with 0 clicks?-| YES --> Check: is the ad relevant to this query?-| | Ad is relevant --> Query may be too broad/informational; monitor-| | Ad is NOT relevant --> Likely in wrong ad group; check keyword/ad group mapping-| NO --> Continue evaluation-|-+-- Has 1-2 conversions at acceptable CPA?-| YES --> Monitor for 30 more days; add as keyword if conversions continue-| NO --> Continue evaluation-|-+-- Relevance score 1-2?- YES --> Add as negative even without click data (proactive hygiene)- NO --> No action needed; review again next period-```+## Current Google anchors-### Mining Frequency+Checked 2026-09-09:-| Account Spend | Review Frequency | Minimum Data Window |-|--------------|-----------------|---------------------|-| < $1,000/month | Monthly | 30 days |-| $1,000-$5,000/month | Bi-weekly | 14 days |-| $5,000-$20,000/month | Weekly | 7 days |-| > $20,000/month | Twice weekly | 3-7 days |+- [Google Ads keyword matching](https://support.google.com/google-ads/answer/14996023)+- [Your guide to broad match](https://support.google.com/google-ads/answer/12159290)+- [Build effective keyword lists](https://support.google.com/google-ads/answer/10039665)+- [About negative keyword lists](https://support.google.com/google-ads/answer/2453983)------## Important: Negatives Are Now a Supplementary Layer (2026)--Traditional negative keyword lists remain useful but are no longer the primary lever for query control. Several Google Ads changes have reduced their precision:--- **Brand Exclusions**: Campaign-level brand exclusion lists (launched 2023, expanded 2024-2025) are now the recommended way to block competitor or irrelevant brand traffic. They work at the brand-entity level, not the keyword level, so they catch variations that keyword negatives miss.-- **Account-Level Suitability Settings**: Google's account-level content suitability and brand safety controls filter categories of queries before negative keywords are even evaluated. Check these settings before building extensive negative lists.-- **Search Themes (Performance Max / Broad Match)**: Google's AI-driven query expansion (Search Themes in PMax, and Broad match's intent matching) can serve ads on queries that don't contain any of your keyword text. Negative keywords only block queries containing the negative term literally — they cannot block conceptually related queries that the AI matches to. This means negative keyword lists give **false confidence** in query control when running Broad match or PMax campaigns.-- **Google's LLM-powered bidding** has real-time signal advantages (device, location, time, audience, query context) that static negative lists cannot replicate. Smart Bidding can effectively "negative out" low-value queries by bidding them down to near-zero, often more precisely than manual negatives.--**Bottom line**: Use negatives for clear-cut exclusions (job seekers, DIY, competitors you don't want to conquest). But don't rely on them as your primary quality control mechanism — Brand Exclusions, suitability settings, and Smart Bidding now carry more of that weight.-------## Negative Keyword Strategy--### Negative Match Type Selection--| Negative Match Type | Syntax | What It Blocks | When to Use |-|--------------------|--------|---------------|-------------|-| **Negative Broad** | `free` | Any query containing the word "free" in any order | Block a single toxic word across all contexts |-| **Negative Phrase** | `"free plumber"` | Queries containing "free plumber" in that order | Block a specific phrase but allow other uses of individual words |-| **Negative Exact** | `[free plumber near me]` | Only that exact query | Block one specific query without risking over-blocking |--### Negative Match Type Decision Tree--```-Is the word ALWAYS irrelevant regardless of context?- YES --> Negative broad match (e.g., "free", "jobs", "salary")- NO --> Continue--Is the phrase irrelevant but individual words might be OK?- YES --> Negative phrase match (e.g., "plumber jobs" — "plumber" alone is fine)- NO --> Continue--Is only this specific query irrelevant?- YES --> Negative exact match (e.g., [plumber salary in texas])-```--### Campaign-Level vs. Ad Group-Level Negatives--| Level | When to Use | Example |-|-------|------------|---------|-| **Ad group level** | Block terms from triggering in one ad group but allow in another | "plumber" negative in HVAC ad group; still active in Plumbing ad group |-| **Campaign level** | Block terms from the entire campaign | "jobs" negative at campaign level for all service campaigns |-| **Negative keyword list (shared)** | Block terms across multiple campaigns | Universal exclusion list: "free", "DIY", "salary", "reddit", "youtube" |--### Universal Negative Keyword Lists--Build these shared lists and apply across all campaigns in the account. **Caveat (2026):** These lists are a useful starting point for clear-cut exclusions, but they give false confidence when running Broad match or Performance Max campaigns. Google's Search Themes and AI-driven query expansion can serve ads on conceptually related queries that don't literally contain any of these negative terms. Treat these lists as a supplementary layer, not a complete shield.--#### General Exclusions (Apply to All Commercial Campaigns)--| Category | Negative Keywords | Match Type |-|----------|------------------|------------|-| **Job seekers** | jobs, careers, hiring, salary, pay, wage, resume, indeed, glassdoor, interview | Broad |-| **Education / DIY** | how to, tutorial, DIY, learn, course, class, training, certification, school, university | Broad |-| **Free / cheap seekers** | free, cheap, cheapest, discount code, coupon, promo code, giveaway | Broad |-| **Information seekers** | what is, definition, meaning, wiki, wikipedia, history of | Phrase |-| **Social / entertainment** | reddit, youtube, tiktok, pinterest, instagram, forum, meme, video | Broad |-| **Complaints / reviews** | complaint, scam, lawsuit, ripoff, BBB, better business bureau | Broad |--#### Industry-Specific Exclusion Patterns--| Industry | Additional Negatives | Rationale |-|----------|---------------------|-----------|-| **Legal** | "pro bono", "legal aid", "free consultation" (if not offered), "law school" | Filters out non-paying prospects |-| **Home Services** | "DIY", "home depot", "lowes", "parts", "tools" | Filters out DIYers who won't hire |-| **SaaS** | "open source", "free alternative", "github", "self-hosted" | Filters out non-buyers |-| **Healthcare** | "symptoms", "webmd", "home remedy", "natural cure" | Filters out info-seekers |-| **E-commerce** | "used", "refurbished", "craigslist", "ebay", "amazon" (if not selling there) | Filters out bargain hunters and marketplace traffic |-| **Real Estate** | "zillow", "trulia", "rent", "section 8" (if selling, not renting) | Filters out renters and portal users |-| **Education** | "free", "scholarship", "financial aid" (if paid-only programs) | Filters out non-paying students |-| **Finance** | "calculator", "formula", "excel template", "reddit" | Filters out DIY finance people |-------## N-gram Analysis Framework--N-gram analysis identifies recurring word patterns in search terms to find systematic waste or opportunity.--### How to Run N-gram Analysis--1. Export search term report (last 30-90 days)-2. Split each search term into individual words (unigrams), word pairs (bigrams), and three-word phrases (trigrams)-3. Aggregate clicks, cost, impressions, conversions, conversion value, distinct queries, campaigns, and ad groups by each n-gram-4. Sort by cost descending to find the most expensive patterns-5. Classify each pattern into an action bucket before recommending a mutation--### Generalized Action Buckets--| Bucket | Signal | Action |-|--------|--------|--------|-| Negative candidate | Irrelevant intent, wrong geography, job seeker, DIY/info, free/cheap when not offered, unwanted competitor/name-seeking | Add negative after checking positive/search-term conflicts |-| Keyword candidate | Converting query/n-gram not present as a positive keyword | Add as exact or phrase in the most relevant ad group |-| Routing candidate | Same query/n-gram served by multiple ad groups with divergent CPA/CVR | Add keyword to the best-fit ad group and negative-route from the wrong group |-| Ad/LP mismatch | Relevant query, poor performance, weak ad relevance or LPX | Rewrite RSA, split ad group, or improve landing page message match |-| Product/content opportunity | Repeated relevant demand not currently targeted or sold | Flag opportunity; do not negative unless business confirms it is unwanted |--High-spend/no-conversion n-grams are review triggers, not automatic negatives. Always inspect examples.--### Common High-Waste N-grams (Cross-Industry)--| N-gram | Typical Waste Signal | Action |-|--------|---------------------|--------|-| "free" | High clicks, near-zero conversions | Add as broad negative |-| "jobs" / "careers" | Job seekers, not customers | Add as broad negative |-| "salary" / "pay" | Job seekers | Add as broad negative |-| "DIY" | Will not hire/buy | Add as broad negative |-| "reddit" | Looking for opinions, not buying | Add as broad negative |-| "youtube" | Looking for video content | Add as broad negative |-| "near me" | High intent if local business; irrelevant if not | Keep if local; negative if not local |-| "reviews" | Can be high intent (commercial investigation) | Keep; optimize landing page |-| "vs" / "versus" | Comparison shoppers; moderate intent | Keep; ensure comparison content on LP |-| "best" | High commercial intent | Keep; prioritize in ad copy |-| "how to" | Informational intent; low conversion | Add as phrase negative for commercial campaigns |-| "what is" | Pure informational | Add as phrase negative |-| "cost" / "price" / "pricing" | High commercial intent — ready to buy | Keep; ensure pricing info on LP |-------## Search Term Categorization Framework--Categorize search terms by intent to determine campaign-level strategy.--| Category | Signal Words | Conversion Likelihood | Campaign Strategy |-|----------|-------------|----------------------|-------------------|-| **High-Intent Commercial** | buy, hire, cost, price, near me, quote, book, order, best + [product] | High (5-15% conv rate) | Bid aggressively; dedicated ad groups; specific landing pages |-| **Comparison / Evaluation** | vs, compare, review, alternative, top, best + [category] | Medium (2-5% conv rate) | Moderate bids; comparison landing pages; remarketing |-| **Informational** | how to, what is, why, guide, tutorial, tips | Low (0.5-2% conv rate) | Low bids or exclude; content marketing channel instead |-| **Navigational** | [brand name], [competitor name], login, website | Variable | Own brand: bid high. Competitor: moderate bid with competitor LP |-| **Irrelevant** | jobs, salary, free, DIY, meme, youtube | Near zero | Add as negative immediately |-------## Search Term Report Analysis Cadence--| Time Period | Analysis Task | Key Questions |-|------------|--------------|---------------|-| **Weekly** | Review top 50 search terms by spend | Any new irrelevant terms burning budget? |-| **Weekly** | Check terms with 10+ clicks, 0 conversions | Are these terms worth continued investment? |-| **Bi-weekly** | Mine converting search terms | Any new terms with 3+ conversions to add as keywords? |-| **Monthly** | Full n-gram analysis | Any systematic waste patterns? New negative keyword lists needed? |-| **Monthly** | Review negative keyword lists | Any over-blocking (negatives killing good traffic)? |-| **Quarterly** | Match type performance audit | Are broad match terms converting at acceptable CPA? Should any be tightened to phrase/exact? |--### Match Type Performance Evaluation--| Match Type | Acceptable CPA vs. Account Avg | Action if CPA Exceeds Threshold |-|-----------|-------------------------------|-------------------------------|-| Exact Match | CPA <= 100% of account average | This is your baseline; if even exact is too expensive, the keyword itself is the problem |-| Phrase Match | CPA <= 130% of account average | Review search terms; add negatives for irrelevant phrase matches |-| Broad Match | CPA <= 160% of account average | Review search terms aggressively; consider tightening to phrase; ensure smart bidding is active |--**Rule**: If broad match CPA is > 200% of exact match CPA for the same keyword, review search terms and add negatives or Brand Exclusions. Switching to Phrase match is unlikely to help given the near-complete semantic overlap between Phrase and Broad in most verticals (2026). Instead, ensure Smart Bidding (tCPA or tROAS) is active — Google's LLM bidding has real-time signal advantages that adjust bids per query more precisely than match type restrictions. If CPA remains unacceptable after negative refinement and Smart Bidding, consider pausing the broad match variant and running exact match only.-------## Wasted Spend Audit--### Calculating Wasted Spend--```-Wasted spend = Cost from search terms with Relevance Score 1-2- + Cost from search terms with 15+ clicks and 0 conversions- - Cost from those terms that generated assisted conversions--Healthy account: Wasted spend < 10% of total spend-Needs work: Wasted spend 10-20% of total spend-Critical: Wasted spend > 20% of total spend-```--### Top Wasted Spend Patterns--| Pattern | How to Identify | Fix |-|---------|----------------|-----|-| Broad match runaway | High spend, low relevance search terms, mostly from broad match keywords | Add negatives and Brand Exclusions; ensure Smart Bidding is active; if CPA remains unacceptable, switch to exact match only |-| Wrong-intent matches | Commercial keyword matching to informational queries | Add informational signal words as negatives |-| Competitor term leakage | Your ads showing for competitor brand names (unintentionally) | Add competitor names as exact negatives (unless conquesting) |-| Geographic mismatch | Queries from locations you don't serve | Tighten location targeting; add location negatives |-| Language mismatch | Queries in languages you don't serve | Check campaign language settings |+Re-verify current platform behavior when the decision depends on it.diff --git a/google-ads/manage/references/session-checks.md b/google-ads/manage/references/session-checks.mdindex 9be6c00b..405a45e1 100644--- a/google-ads/manage/references/session-checks.md+++ b/google-ads/manage/references/session-checks.md@@ -13,20 +13,20 @@ Read `{data_dir}/change-log.json`. Find entries where `reviewed` is `false`.> _[Date]: [summary]_> Google Ads needs time to accumulate enough data for a reliable before/after comparison. Ready for review on [reviewAfter date] ([reviewWindow] review window per `change-tracking.md`).-Do NOT pull metrics or attempt to assess impact early — small sample sizes lead to misleading conclusions.+Do not declare the primary outcome early. You may still pull safety, spend, delivery, measurement, and policy signals needed to detect a breached guardrail; label the business-outcome verdict immature until the recorded maturity rule is satisfied.**If unreviewed changes exist AND `reviewAfter` has passed:**-1. Pull current metrics for the affected campaigns over the last 7 days using an available reporting capability scoped to those IDs. Use the `beforeSnapshot` from the change log as the baseline — only query the pre-change period directly if `beforeSnapshot.metrics` is null. Do this in parallel with the user's actual request, and reuse the resulting rows for the anomaly check below.+1. Pull current metrics for the affected entities over the recorded review window using an available reporting capability scoped to those IDs. Use the `beforeSnapshot` only when its definitions, denominator, scope, and maturity match; otherwise query a complete like-for-like pre-change period. Do this alongside the user's actual request, and reuse the resulting rows for the anomaly check below.-2. Compute deltas: percentage change for spend, conversions, CPA, CTR.+2. Compute the primary business metric and guardrail recorded for the intervention. Add spend, conversion, CPA, or CTR deltas only when their definitions and denominators are comparable.3. Present briefly BEFORE the user's request:> **Follow-up on recent changes:**>> _[Date]: [summary]_-> Result after [7/14] days: CPA went from $X -> $Y ([+/-Z%]). Conversions [increased/decreased] from X -> Y. [One sentence assessment]+> Result after [review window]: [primary metric] went from X to Y ([+/-Z%]) on [named denominator]. [Guardrail] changed from A to B. [One sentence assessment, including maturity or comparability limits.]4. Mark as `reviewed: true` with `reviewResult`:```json@@ -41,14 +41,14 @@ Do NOT pull metrics or attempt to assess impact early — small sample sizes lea}```-5. If `negative` (CPA increased >20% or conversions dropped >20%): suggest undoing.+5. If the predeclared rollback threshold is breached on mature, comparable evidence, recommend the recorded rollback. If no threshold was recorded, classify the result as observed/inconclusive and ask for the business guardrail rather than inventing one after seeing the outcome.## Check account baseline for anomaliesRead `{data_dir}/account-baseline.json`. If it exists AND was last updated >24 hours ago:-1. Compare each campaign's 7-day metrics to the `rolling30d` baseline.-2. Flag campaigns where CPA is >1.5x average, conversions dropped >40%, spend rate >1.5x average, or CTR dropped >30%.+1. Compare each campaign's most recent complete window with a like-for-like mature baseline.+2. Flag movements that cross a stored account-specific anomaly band or business guardrail. If none exists, rank the largest standardized or percentage movements for review and label them as triage signals, not failures.3. Mention anomalies briefly if found.4. Update the baseline (see Account Baseline section in SKILL.md).diff --git a/google-ads/shared/analysis-principles.md b/google-ads/shared/analysis-principles.mdindex 43c1133e..10c04cc8 100644--- a/google-ads/shared/analysis-principles.md+++ b/google-ads/shared/analysis-principles.md@@ -12,6 +12,14 @@ Every claim or recommendation must cite specific data **from this account**:- When recommending an action, separately show the data that *would falsify* the recommendation if it existed. ("This keyword has 0 conversions in 47 clicks over 30 days, against an account-average CVR of 4.2% — expected ~2 conversions, observed 0.")- "Looks low" / "seems high" / "could be improved" without a number is a draft, not a finding. Pull the number or cut the bullet.+Before comparing numbers, reconcile what they mean. Keep the metric definition, conversion action or goal, source, denominator, attribution basis, account timezone, date window, and reporting maturity visible when any of them could change the conclusion. A Google Ads `Conversions` total, `All conversions`, a CRM-qualified lead count, and an analytics event count are not interchangeable.++Label the reasoning layer:++- **Observed:** directly supported by the returned data.+- **Inferred:** a plausible explanation with the evidence for and against it.+- **Causal:** supported by a controlled experiment or another credible identification strategy. A before/after movement alone is not causal proof.+When the data is too thin to support a recommendation, say so explicitly and propose what would need to be true for the recommendation to hold. Don't paper over uncertainty.## High-level approach (you decide the specifics)@@ -21,14 +29,26 @@ Choose tools, query shape, and analytical depth from the user's question and theWhat does need to be true on every analysis:1. **Scope the evidence.** Read enough to answer the question. Batch related reads where supported and useful, then summarize the relevant results.-2. **Correlate, don't isolate.** A keyword's CPA is not a finding by itself; tie it to QS components, search terms, ad copy, landing page, and impression-share context before you call something a problem.-3. **Verify before mutating.** Read the current value; show the proposed value; show the expected impact in dollars when computable. Get a yes, then write.+2. **Reconcile before comparing.** Check equivalent scope, definitions, denominators, date completeness, conversion lag, attribution, and duplicated or missing coverage.+3. **Correlate, don't isolate.** A keyword's CPA is not a finding by itself; tie it to search terms, business intent, conversion quality, ad/landing-page match, and delivery constraints before you call something a problem. Use Quality Score only as a diagnostic clue.+4. **Make the decision testable.** State the action now, what is deferred, the primary metric and denominator, observation window, maturity rule, and keep/hold/rollback condition.+5. **Verify before mutating.** Read the current value; show the proposed value; show the expected impact as a scenario rather than a promise. Get a yes, then write.++For a material recommendation, run a short consistency check before answering:++- all decision-changing supplied evidence was either used or explicitly ruled irrelevant;+- every distinct quantitative block has an applicable derived statistic or an explicit reason it cannot affect the decision;+- derived values show their inputs, denominators, and units;+- the advertiser's target or verified economic threshold appears in the decision rule;+- the recommended action can generate the evidence required for its own review;+- the recommendation and every keep/hold/rollback branch agree with the arithmetic.## Guardrails (do not violate)-- **STOP if conversion tracking is broken.** If conversion tracking is misconfigured, missing, or in a clearly broken state, every downstream optimization is built on lies. Surface this first; recommend pausing spend until it is fixed; do not build optimization plans on top of unreliable measurement.-- **Never pause a Tier 1 (core business) keyword on short-window data.** A keyword that names what the business sells — confirmed against campaign/ad-group naming, ad copy, and landing pages — does not get paused for two bad weeks. Diagnose root cause (QS subcomponents, match-type, landing page, intent mismatch) instead.-- **Statistical significance gate.** Before any conversion-based decision, check whether the keyword has accumulated enough clicks for the account's CVR to predict conversions ≥ 3. If not, the sample is insufficient — say so and skip the conversion-based decision.+- **STOP conversion-led optimization if measurement is unreliable.** Surface the fault first and do not change bidding, budgets, or targeting based on untrusted CPA/ROAS. Recommend a protective pause or spend reduction only when exposure cannot be bounded by a trustworthy guardrail, and only within the user's authorization. Otherwise preserve known-safe delivery while measurement is repaired.+- **Do not pause a Tier 1 (core business) keyword solely from short-window performance.** Diagnose measurement, maturity, search-term intent, ad/landing-page match, delivery constraints, and business economics first. A protective reduction can still be justified by clearly irrelevant traffic or a breached, predeclared spend guardrail.+- **No magic sample threshold.** Evidence sufficiency depends on the decision risk, effect size, conversion cycle, attribution maturity, spend exposure, and baseline rate. Use expected conversions or uncertainty intervals as diagnostics when inputs support them, but never treat a fixed click or conversion count as universal proof. For Smart Bidding changes, normally wait until the relevant conversions have matured and assess over one to two conversion cycles unless a safety or spend guardrail requires earlier action.+- **One-variable causal tests.** For material uncertain changes, prefer an experiment with a written hypothesis, one primary business metric, a guardrail, and one changed variable. Do not call a winner while the platform reports the result as undecided or while material conversions remain immature.- **Respect capability boundaries.** Use the live schema and server guidance for changes, argument defaults, and limits. Do not bypass a rejected operation by splitting it into smaller calls.- **Verify rollback support.** Record operation identifiers and before/after state. Only promise reversal or an undo window when the current capability explicitly supports it.- **Confirm the scope of bulk changes.** Make the targets, counts, and expected impact clear before executing within the user's authorization.diff --git a/google-ads/shared/ppc-math.md b/google-ads/shared/ppc-math.mdindex 3dc50fd5..73b3c169 100644--- a/google-ads/shared/ppc-math.md+++ b/google-ads/shared/ppc-math.md@@ -2,7 +2,7 @@Formulas and interpretation rules used throughout the Google Ads skills. Load this when a finding needs dollar-denominated impact, profitability framing, or a forecast.-**Priority rule:** When `business-context.json` has `profit_margin` and `aov`, use break-even-based thresholds. Otherwise fall back to account-average heuristics in `analysis-heuristics.md`. Never mix the two in a single finding — the framing should be consistent.+**Priority rule:** Use a business target or break-even threshold only when the underlying contribution economics are verified for the same outcome and payback window. Otherwise use mature account history as directional context, not as proof of profitability. Keep the chosen denominator and economic basis consistent within a finding.---@@ -11,7 +11,8 @@ Formulas and interpretation rules used throughout the Google Ads skills. Load th```CPA = Spend / ConversionsROAS = Revenue / Spend (ratio, e.g. 3.5x)-ROAS% = (Revenue - Spend) / Spend × 100+ROAS% = Revenue / Spend × 100+Marketing ROI% = (Contribution Profit - Ad Spend) / Ad Spend × 100CPC = Spend / ClicksCPM = (Spend / Impressions) × 1000CTR = Clicks / Impressions × 100@@ -19,24 +20,89 @@ CVR = Conversions / Clicks × 100CPL = Spend / Leads```-## Profitability Formulas (require margin + AOV)+## Evidence integrity and coverage++Use these when platform rows, CRM outcomes, imports, or a displayed extract may be incomplete or duplicated. Keep each denominator named; do not call two rates comparable merely because both are percentages.```-Break-Even CPA = AOV × Profit Margin-Max Profitable CPA = Break-Even CPA (bid up to this, no higher)-Break-Even ROAS = 1 / Profit Margin-Unit Profit = AOV × Profit Margin - CPA-Headroom $ = (Break-Even CPA - Current CPA) × Monthly Conversions+Extract Coverage = Extract Rows / Eligible Source Rows+Join Coverage = Matched Unique IDs / Eligible Unique Source IDs+Duplicate Rate = Duplicate Rows / Observed Rows+Deduplicated Coverage = Unique Matched IDs / Eligible Unique Source IDs+Timestamp-valid Rate = Rows Inside Valid Window / Eligible Rows+Unresolved Rate = Unresolved Eligible IDs / Eligible Unique Source IDs+```++State what makes a row eligible and whether the numerator is raw rows, unique identifiers, conversions, leads, or customers. A high raw join rate can coexist with weak unique-ID coverage when duplicates are present.++## Incomplete outcomes and bounds++When unresolved records could change the decision, show bounds rather than silently dropping them:++```+Worst-case Outcomes = Confirmed Outcomes+Best-case Outcomes = Confirmed Outcomes + Eligible Unresolved Outcomes+Worst-case CPA = Spend / Worst-case Outcomes+Best-case CPA = Spend / Best-case Outcomes+```++Reverse the labels when the outcome is undesirable, such as refunds or invalid leads. Use only plausible eligible unresolved rows; do not count records known to be duplicates, outside the window, or outside the decision scope.++## Conversion maturity and cohort weighting++Do not blend immature and mature cohorts as if they had equal observation time.++```+Projected Mature Outcomes for Cohort = Observed Outcomes / Completion Fraction+Projected Mature CPA = Cohort Spend / Projected Mature Outcomes+Weighted Mature Rate = Sum(Mature Outcomes) / Sum(Eligible Inputs)+Weighted Mature CPA = Sum(Spend) / Sum(Mature Outcomes)```-**Headroom interpretation:**+Require `0 < Completion Fraction <= 1`; otherwise do not project. Treat completion-fraction projections as maturity adjustments, not causal forecasts. Prefer actual mature cohorts when available, and state the conversion-cycle date or completion gate for the final decision.++## Target gaps and cleaned counterfactuals++```+Spend at Target CPA = Outcomes × Target CPA+Spend Above Target = max(0, Spend - Spend at Target CPA)+CPA Headroom per Outcome = Target CPA - Current CPA+Cleaned Spend = Total Spend - Identified Out-of-scope Spend+Cleaned Outcomes = Total Outcomes - Identified Out-of-scope Outcomes+Cleaned CPA = Cleaned Spend / Cleaned Outcomes+```-| Headroom | Framing | Action |-|---|---|---|-| Negative | "Losing $X/month on this campaign" | Pause or restructure immediately |-| $0-$500/mo | "Barely break-even" | Improve QS / CVR before scaling |-| $500-$2,000/mo | "Profitable but tight" | Selective scaling |-| >$2,000/mo | "Strong unit economics" | Scale aggressively (20% rule) |+For a rate-versus-cost decomposition, hold one factor at its prior value at a time:++```+CPA at Current CPC and Prior CVR = Current CPC / Prior CVR+CPA at Prior CPC and Current CVR = Prior CPC / Current CVR+```++These are counterfactual decompositions, not proof that one factor caused the change. Label any remainder and name other plausible explanations.++## Incrementality and break-even++```+Incremental CPA = Incremental Spend / Incremental Outcomes+Break-even Incremental Count = Incremental Spend / Contribution per Outcome+Incremental Contribution = (Incremental Outcomes × Contribution per Outcome) - Incremental Spend+```++Use treatment-minus-control outcomes or another credible incremental estimate. Attributed outcomes are not automatically incremental. If no control or credible counterfactual exists, propose a bounded experiment instead of presenting attributed CPA as incrementality.++## Profitability Formulas (require verified contribution economics)++```+Contribution / Order = Net Revenue - variable fulfillment, returns, fees, and service costs+Break-Even CPA = Contribution per acquired customer over the chosen payback window+Max Profitable CPA = Break-Even CPA minus the business's required profit or risk buffer+Break-Even ROAS = 1 / Contribution Margin (only when value is comparable revenue)+Unit Contribution = Contribution per acquired customer - CPA+Headroom $ = (Break-Even CPA - Current CPA) × Monthly Conversions+```++Headroom is a scenario at the observed volume, not proof of incremental profit. Returns, lead quality, close rate, repeat purchases, capacity, taxes, and marginal media efficiency can change it. Use the advertiser's target and payback constraint rather than universal dollar bands.---@@ -49,28 +115,22 @@ LTV:CAC = LTV / CACPayback = CAC / (ARPU × Gross Margin) (months to recover CAC)```-| LTV:CAC | Interpretation |-|---|---|-| <1:1 | Losing money on every customer. Stop scaling immediately |-| 1:1–3:1 | Marginal. Viable only if payback period < 12 months |-| 3:1 | Healthy (SaaS/service benchmark) |-| 5:1+ | Under-investing in growth. You can afford to bid higher |+Interpret LTV:CAC only against the business's gross margin, cash constraints, retention maturity, and payback target. A high ratio can reflect understated CAC or immature growth rather than under-investment; a low ratio does not by itself identify which campaign to change.---## Impression Share Opportunity```-Revenue Opportunity = Current Revenue × (1 / Current IS - 1)-Budget to Capture Full IS = Current Spend × (1 / Current IS)+Eligible Revenue Upper Bound = Current Revenue × (1 / Current IS - 1)+Linear Spend Upper Bound = Current Spend × (1 / Current IS)```**Example:** Campaign at 60% IS, spending $3,000/mo, generating $12,000 revenue.-- Full-IS revenue potential: $12,000 × (1/0.6 - 1) = **$8,000/mo additional**-- Budget to capture it: $3,000 × (1/0.6) = **$5,000/mo**-- Incremental: spend $2,000 more → capture $8,000 more revenue (4x ROAS on incremental)+- Linear eligible-revenue upper bound: $12,000 × (1/0.6 - 1) = **$8,000/mo additional**+- Linear spend upper bound: $3,000 × (1/0.6) = **$5,000/mo**-**Only use this framing when Budget-Lost IS is the constraint (Layer 4 Scale).** If Rank-Lost IS is the constraint, increasing budget does nothing — the formula mis-frames the problem.+These calculations assume the missed auctions behave like the observed auctions, which is rarely guaranteed. Label them as bounds, never forecasts. Only use them when budget loss is material and rank, demand, query quality, capacity, and mature economics have been checked. Prefer Google's simulator or a staged test for a decision.---@@ -82,15 +142,9 @@ Projected Conversions = Projected Spend / Historical CPAProjected Revenue = Projected Conversions × AOV```-Present 3 scenarios, enforcing the **20% scaling rule** (never recommend more than +20% in a single week; compound across weeks):+Treat these as sensitivity scenarios, not forecasts. Choose candidate budgets from the account's actual constraint, simulator output where available, cash/capacity ceiling, and acceptable downside. There is no universal safe percentage that guarantees learning will not change.-| Scenario | Weekly Budget Increase | Caveat |-|---|---|---|-| Conservative | +20% | Safest — no learning phase reset |-| Moderate | +50% over 3 weeks (+20%, +25%, +25% compounded) | Monitor for CPA drift after each step |-| Aggressive | +100% over 5 weeks | Diminishing returns kick in; expect CPA to rise 15–25% |--Always show the **diminishing returns warning** for aggressive: "Doubling budget rarely doubles conversions — expect 1.5–1.7x conversions at 2x spend."+For a Smart Bidding target or conversion-goal change, isolate the change when practical and define the evaluation window in conversion cycles. Google's current guidance says performance commonly takes one to two conversion cycles to reflect a target or goal change; avoid repeated target changes inside one cycle unless a business guardrail requires intervention.---@@ -100,13 +154,7 @@ Always show the **diminishing returns warning** for aggressive: "Doubling budgetMER = Total Business Revenue / Total Marketing Spend```-Use MER when the user has multi-channel spend and wants blended efficiency. Typical ranges by industry template (see `industry-templates.json`):--| Industry | Typical MER | Excellent |-|---|---|---|-| Ecommerce | 3–5x | 8x+ |-| SaaS | 5–10x | 15x+ |-| Local Service | 3–8x | 10x+ |+Use MER when the user has multi-channel spend and wants blended efficiency. Compare it with the business's own contribution, payback target, and mature like-for-like history. External industry ranges are directional context only and do not establish a healthy account-level target.MER captures organic, brand, and retention — so it's higher than paid ROAS and should never be compared directly to ROAS.@@ -117,19 +165,19 @@ MER captures organic, brand, and retention — so it's higher than paid ROAS and**Before (account-average framing):**> "Keyword 'emergency plumber example-city' has CPA of $72, which is 150% of account average."-**After (margin-aware framing, requires `margin=0.4`, `aov=$180` from business-context.json):**-> "Keyword 'emergency plumber example-city' has CPA of $72. Your Break-Even CPA is $72 (AOV $180 × 40% margin) — every conversion from this keyword nets $0 profit. Either improve CVR or pause."+**After (contribution-aware framing, requires a verified $72 contribution per acquired customer over the chosen payback window):**+> "Keyword 'emergency plumber example-city' has CPA of $72 against a verified $72 break-even CPA. It has no contribution headroom at the observed volume. Hold scaling; diagnose query and conversion quality, then test the smallest plausible improvement or reduce exposure if the business guardrail is breached."**Headroom example:**-> "Example City Search is profitable: CPA $18, Break-Even $72, **~$2,700/mo headroom** at 50 conversions. Budget-Lost IS is 35% — raising budget by $1,500/mo could capture ~$5,000 more revenue."+> "Example City Search has $54 of CPA headroom against a verified $72 break-even CPA. At the observed 50 monthly conversions, that is a **$2,700 contribution-headroom scenario**. With 35% lost impression share to budget, a linear calculation gives an eligible-revenue upper bound, not expected incremental revenue; use a simulator or staged budget test to estimate the marginal return."-The second framing is concretely actionable. The first is a number without a verdict.+The second framing is auditable when the contribution inputs and outcome denominator are verified. If they are not, label it as a sensitivity scenario rather than an action threshold.---## Gates-1. **Never compute break-even without verified margin.** If `business-context.json.profit_margin` is missing or marked `inferred_from_template`, label the output "estimated from industry template (±20%)" and ask the user to confirm before any write operation.-2. **Never project conversions more than 2x current spend.** Diminishing returns make linear projections unreliable beyond that.+1. **Never compute break-even from gross margin alone when material variable costs, lead-to-sale rate, repeat value, refunds, or capacity are missing.** If inputs are inferred, label the output as a scenario and do not use it to authorize a write.+2. **Do not present linear conversion projections as expected outcomes.** Bound the scenario to observed support, show the assumption, and use a simulator, experiment, or staged change for material scaling.3. **Never use MER in place of ROAS for individual-campaign decisions.** MER is a blended portfolio metric; individual campaigns must clear ROAS/CPA targets.-4. **LTV:CAC requires ≥12 months of history.** If the business is newer, fall back to payback period only.+4. **LTV must match the cohort and maturity needed for the decision.** If retention is immature, show a shorter verified contribution/payback window rather than extrapolating a lifetime value.diff --git a/plugin.json b/plugin.jsonindex 30562fbe..776948e3 100644--- a/plugin.json+++ b/plugin.json@@ -1,7 +1,7 @@{"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json","name": "notfair",- "version": "0.27.6",+ "version": "0.27.7","description": "Operate ads and analytics, and run open-source SEO, GEO, and content workflows from compatible AI agents.","author": {"name": "NotFair",diff --git a/server.json b/server.jsonindex 0298a3a7..cbafdd49 100644--- a/server.json+++ b/server.json@@ -8,7 +8,7 @@"url": "https://github.com/nowork-studio/notfair-plugin","source": "github"},- "version": "0.27.6",+ "version": "0.27.7","remotes": [{"type": "streamable-http",