{
  "skill_name": "google-ads",
  "evals": [
    {
      "id": 1,
      "prompt": "Can you help me manage my Google Ads?",
      "expected_output": "The skill checks for the NotFair MCP server connection, then resolves config from the 3-tier chain (project .notfair.json > Claude project notfair.json > global ~/.notfair/config.json), then checks for an accountId. It should not attempt to pull campaign data before completing the onboarding flow.",
      "files": [],
      "expectations": [
        "The skill attempts to verify MCP server connectivity before pulling data",
        "The skill resolves accountId from the 3-tier config chain (project > claude-project > global); auth is handled by Claude Code's native HTTP+OAuth transport, not by an API key in config",
        "The skill checks for accountId before making campaign API calls",
        "If any setup step is missing, the skill guides the user through resolution before proceeding"
      ]
    },
    {
      "id": 2,
      "prompt": "Here's my Google Ads data. I have 3 campaigns:\n\n```json\n{\"campaigns\": [{\"name\": \"Brand - Acme Plumbing\", \"id\": \"111\", \"status\": \"ENABLED\", \"spend_30d\": 2400, \"clicks\": 890, \"impressions\": 12000, \"conversions\": 45, \"cpa\": 53.33, \"ctr\": 7.4}, {\"name\": \"Non-Brand - Emergency Plumbing\", \"id\": \"222\", \"status\": \"ENABLED\", \"spend_30d\": 4800, \"clicks\": 620, \"impressions\": 18000, \"conversions\": 12, \"cpa\": 400.00, \"ctr\": 3.4}, {\"name\": \"Non-Brand - Drain Cleaning\", \"id\": \"333\", \"status\": \"ENABLED\", \"spend_30d\": 1800, \"clicks\": 410, \"impressions\": 9500, \"conversions\": 18, \"cpa\": 100.00, \"ctr\": 4.3}],\n\"keywords\": [{\"campaign\": \"Non-Brand - Emergency Plumbing\", \"keyword\": \"emergency plumber near me\", \"spend\": 1200, \"clicks\": 180, \"conversions\": 8, \"cpa\": 150, \"qs\": 7}, {\"keyword\": \"24 hour plumbing service\", \"campaign\": \"Non-Brand - Emergency Plumbing\", \"spend\": 1800, \"clicks\": 220, \"conversions\": 0, \"cpa\": null, \"qs\": 3}, {\"keyword\": \"plumber salary\", \"campaign\": \"Non-Brand - Emergency Plumbing\", \"spend\": 450, \"clicks\": 95, \"conversions\": 0, \"cpa\": null, \"qs\": 2}, {\"keyword\": \"drain cleaning service\", \"campaign\": \"Non-Brand - Drain Cleaning\", \"spend\": 900, \"clicks\": 210, \"conversions\": 14, \"cpa\": 64.29, \"qs\": 8}],\n\"search_terms\": [{\"term\": \"how to become a plumber\", \"clicks\": 42, \"conversions\": 0, \"spend\": 180}, {\"term\": \"plumbing apprenticeship\", \"clicks\": 28, \"conversions\": 0, \"spend\": 120}, {\"term\": \"emergency plumber example-city\", \"clicks\": 35, \"conversions\": 6, \"spend\": 210}]}\n```\n\nHow are my ads doing? What should I fix?",
      "expected_output": "A performance analysis that identifies specific waste: the 'plumber salary' keyword ($450 spent, 0 conversions, QS 2) should be paused immediately; '24 hour plumbing service' ($1800, 0 conversions, QS 3) needs urgent attention; 'how to become a plumber' and 'plumbing apprenticeship' should be added as negative keywords. The Emergency Plumbing campaign has a $400 CPA which is far above the Drain Cleaning campaign's $100 CPA. Should recommend adding 'emergency plumber example-city' as a keyword since it has 6 conversions.",
      "files": [],
      "expectations": [
        "Identifies 'plumber salary' keyword as waste — names it specifically with the $450 spend and 0 conversions",
        "Identifies '24 hour plumbing service' as problematic — $1800 spend, 0 conversions, QS 3",
        "Recommends adding 'how to become a plumber' and 'plumbing apprenticeship' as negative keywords",
        "Recommends adding 'emergency plumber example-city' as a keyword since it has 6 conversions",
        "Flags the Emergency Plumbing campaign's $400 CPA as significantly worse than Drain Cleaning's $100 CPA",
        "Calculates or estimates wasted spend with a dollar amount",
        "Recommendations include specific keyword names and campaign names, not generic advice"
      ]
    },
    {
      "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": "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": [
        "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"
      ]
    },
    {
      "id": 4,
      "prompt": "Check today's keywords for a small bookkeeping Google Ads account. Today has $69 spend, 2 clicks, 39 impressions, 0 conversions; 7d has $227 spend, 9 clicks, 1 conversion. Search terms are 'bookkeeping Seattle' and 'bookkeeping Kirkland'. Campaign is enabled and spending far below daily budget. What is your overview and proposal?",
      "expected_output": "A concise recent-day operator note that reports evaluated metrics, says data is thin, does not recommend a budget increase, does not overfit 2 clicks, and proposes watching search-term quality / rank or landing-page relevance rather than mutating aggressively.",
      "files": [
        "google-ads/manage/references/repeatable-optimization-loops.md"
      ],
      "expectations": [
        "Uses a recent-day/daily-check format with evaluated metrics and 7-day context",
        "Explicitly labels the data as too thin for a strong conversion-based recommendation",
        "Does not recommend increasing budget when spend is far below budget",
        "Focuses next proposal on query quality, rank/relevance, landing page, or watch conditions",
        "Avoids adding negatives for relevant bookkeeping terms without more evidence"
      ]
    },
    {
      "id": 5,
      "prompt": "I have broad match search terms with repeated no-conversion patterns: 'bookkeeping jobs', 'bookkeeper salary', 'free bookkeeping template', 'bookkeeping Seattle', and 'quickbooks cleanup service'. Build a cleanup plan.",
      "expected_output": "The skill should aggregate by n-gram/action bucket, recommend job/salary/free/template as negative candidates, preserve high-intent commercial/local terms like bookkeeping Seattle and quickbooks cleanup service, and check conflicts before bulk negatives.",
      "files": [
        "google-ads/manage/references/search-term-analysis-guide.md",
        "google-ads/manage/references/repeatable-optimization-loops.md"
      ],
      "expectations": [
        "Groups repeated patterns into n-grams instead of treating every query independently",
        "Classifies recommendations into action buckets such as negative candidate, keyword candidate, and ad/LP mismatch",
        "Recommends negatives for job/salary/free/template intent",
        "Does not negative high-intent local/commercial terms solely because they lack conversions",
        "Mentions checking positive-keyword/search-term conflicts before executing bulk negatives"
      ]
    },
    {
      "id": 6,
      "prompt": "Daily CentsIQ ads: yesterday spent $70 on 3 clicks and 0 leads, 7-day baseline is $230 spend, 9 clicks, 1 lead. The main keyword was bookkeeper Seattle. Search terms are relevant but sparse. What should the operator brief say?",
      "expected_output": "A daily ads operator brief with scope/window, snapshot, budget/pacing context, thin-data caveat, watch threshold for bookkeeper Seattle, no aggressive negative or budget change, and an approval queue only if there is a clearly safe action.",
      "files": [
        "google-ads/manage/references/daily-ads-operator.md",
        "google-ads/shared/local-leadgen-playbook.md"
      ],
      "expectations": [
        "Uses daily operator format with scope, snapshot, read, watch, recommendations",
        "Calls out thin data and avoids overfitting 3 clicks",
        "Does not recommend raising budget without budget-lost evidence or proven CPA",
        "Frames bookkeeper Seattle as a watch item with threshold rather than immediate pause",
        "Keeps client/business lead-quality context visible"
      ]
    },
    {
      "id": 7,
      "prompt": "Search term cleanup: broad match produced terms jobs, salary, free template, bookkeeping Seattle, quickbooks cleanup service, and bookkeeping course. Build the proposed actions.",
      "expected_output": "Classifies terms into action buckets; recommends negatives for jobs/salary/free template/course; preserves bookkeeping Seattle and quickbooks cleanup service as watch/keyword candidates unless economics prove otherwise; says approval and conflict checks are required before mutation.",
      "files": [
        "google-ads/manage/references/search-term-triage.md",
        "google-ads/shared/local-leadgen-playbook.md"
      ],
      "expectations": [
        "Groups bad intent patterns rather than treating every term independently",
        "Recommends negatives for employment/training/free-template intent",
        "Does not negative plausible commercial local/service terms solely for no conversions",
        "Mentions conflict checks before negatives",
        "Produces an approval-ready action queue"
      ]
    },
    {
      "id": 8,
      "prompt": "Apply approved negative keywords. The tool returned changeId 123 but success=false with authorization_error=7. What should you tell the user and do next?",
      "expected_output": "Does not claim success; explains that changeId can represent an attempted-change log, verifies live state, preserves the error/request details, compares nearby successful writes, and recommends safe debugging or tool feedback instead of retrying blindly.",
      "files": [
        "google-ads/manage/references/safe-executor.md"
      ],
      "expectations": [
        "Does not treat changeId as proof of live Google Ads state",
        "Requires live read-back verification",
        "Separates failed/unverified writes from successful writes",
        "Preserves useful error details",
        "Avoids blind repeated retries"
      ]
    },
    {
      "id": 9,
      "prompt": "For a NotFair Google Ads MCP campaign on Maximize Clicks with cheap generic MCP traffic and no signups, what should we improve first?",
      "expected_output": "Uses the SaaS/B2B playbook: avoid optimizing for cheap clicks, tighten generic curiosity/search-term waste, improve brand/trust and landing-page message match, prefer activation-level conversions such as connected account or first successful action, and delay budget scaling until query quality and activation signal improve.",
      "files": [
        "google-ads/shared/saas-b2b-playbook.md",
        "google-ads/manage/references/daily-ads-operator.md"
      ],
      "expectations": [
        "Rejects cheap clicks as the success metric",
        "Prioritizes activation-quality conversion signal over raw signup/clicks",
        "Calls out brand trust / unclear relationship risk for tool integrations",
        "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"
      ]
    }
  ]
}

# Analysis Heuristics

This file is calibration data and guardrails. It is **not** a step-by-step checklist — your judgment decides how to apply what's here. Whatever you recommend has to be backed by data from this account (per `../../shared/analysis-principles.md`).

## Framing — margin-aware vs. account-average

Before reasoning about "good" or "bad" performance, check `{data_dir}/business-context.json.unit_economics`:

- **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.

## Guardrail: keyword tier classification (do not skip)

Before evaluating any keyword's performance, classify it. This prevents pausing core business keywords during a short run of poor metrics — the most common AI-agent failure mode.

| 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 | 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: 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: evidence sufficiency

Before a conversion-based decision (pause, bid down, "non-converter" label), check:

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 remembering

These are non-obvious enough that the agent benefits from having them surfaced — they are evidence the AI uses, not rules to apply blindly:

- **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, stop conversion-led optimization and repair measurement first. Use a protective spend action only when exposure cannot otherwise be bounded.

## Impression share — interpret the cause, then test the opportunity

- 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.

# 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.

# Campaign Structure Guide

Structure exists to express different business goals, settings, and intent—not to hit a universal campaign, ad-group, or keyword count.

## Campaign boundary

Use a separate campaign when a meaningful campaign-level control must differ, such as:

- 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.

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.

## Ad-group boundary

Group keywords and ads around a narrow intent that can be answered by the same offer and landing page. Split when:

- 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.

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.

## Restructure diagnosis

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.

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.

## Naming

Names should expose durable operating dimensions, not implementation trivia. A useful pattern is:

`<objective> | <market> | <product-or-intent> | <optional distinction>`

Keep names readable and stable. Put test dates, hypotheses, and owners in labels or intervention records rather than continually renaming entities.

## Current Google anchors

Checked 2026-09-09:

- [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)

Re-verify current UI and capability details before a write.

# Change Tracking

After every successful write operation, log the change to `{data_dir}/change-log.json`.

## Change log entry format

Append to the `changes` array:

```json
{
  "id": "chg_<unix_timestamp_ms>",
  "timestamp": "<ISO 8601>",
  "action": "<action_type>",
  "summary": "<specific one-liner, e.g. 'Paused 5 non-converting keywords in Example Service - Local saving ~$340/month'>",
  "details": {
    "campaignId": "<if applicable>",
    "campaignName": "<if applicable>",
    "affectedEntities": ["<IDs>"],
    "entityNames": ["<keyword text or campaign names>"]
  },
  "beforeSnapshot": {
    "metrics": { "spend30d": 0, "clicks30d": 0, "conversions30d": 0, "cpa30d": 0, "ctr30d": 0 },
    "note": "Metrics for affected entities at time of change"
  },
  "changeIds": ["<changeId(s) returned by write tool>"],
  "reviewAfter": "<ISO 8601 based on conversion maturity and the decision rule>",
  "reviewWindow": "<date range or conversion-cycle rule>",
  "reviewed": false,
  "reviewResult": null
}
```

## Rules

- **Capture before-metrics** from data already in context. If none available: `"beforeSnapshot": { "metrics": null, "note": "No pre-change metrics" }`.
- **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.

## Proactive reminders (SessionStart hook + calendar)

Users shouldn't have to remember to come back. Two complementary mechanisms:

1. **SessionStart hook** — `bin/notfair-change-watch` scans every account's `change-log.json` and prints any entry whose `reviewAfter` has passed and `reviewed == false`. Wire it in `~/.claude/settings.json`:
   ```json
   {
     "hooks": {
       "SessionStart": [
         { "hooks": [ { "type": "command", "command": "/home/user/notfair/bin/notfair-change-watch" } ] }
       ]
     }
   }
   ```
   When the user opens a new Claude session, any pending reviews appear as session context — the assistant can proactively offer to run a scoped `/google-ads-audit`.

2. **Calendar (.ics) reminder** — after logging a change, offer to generate a calendar invite the user can drop into any calendar app:
   ```
   notfair-change-watch ics <account_id> <change_id> > ~/review-<change_id>.ics
   ```
   The .ics file includes a 9-hour-before alarm so the user gets notified on review day. Cross-platform, no cloud dependency, works offline.

# Client Reporter

Use this when converting operator notes into a client-facing account update. The audience wants confidence and business meaning, not raw PPC mechanics.

## Contract

A client update must:

- Lead with status and what changed.
- Use plain English and explain why each recommendation matters.
- Separate verified changes already made from proposed next actions.
- Include the reporting window and key metrics.
- Name open questions that require client/business input.
- Avoid tool jargon unless it affects the client's decision.

## Structure

```text
Subject: <Client> Ads Update — <date/window>

Quick status:
<1-2 sentences>

Performance snapshot:
- Spend:
- Clicks:
- Leads/conversions:
- Avg CPC / CPA:

What we learned:
- <business-readable insight>

Changes made:
- <verified live changes only>

What I recommend next:
1. <proposal>
   Why it matters:
   Risk:
   Approval needed:

Watching:
- <watch item and trigger>

Need from you:
- <business-context question, if any>
```

## Voice

- Crisp, calm, active management.
- No screenshot-style dumps.
- No "the algorithm" hand-waving.
- Make uncertainty explicit: "too early to judge" is better than fake confidence.

## Examples of good framing

- "Traffic is relevant but expensive; we are watching whether these high-intent clicks turn into leads before tightening."
- "I do not recommend raising budget yet because spend is not budget-constrained; the constraint is rank/relevance."
- "This term is job-seeker intent, so blocking it should reduce waste without hurting buyer traffic."

## Anti-patterns

- Sending a client update without explicit send approval.
- Claiming unverified writes as completed.
- Focusing on CTR when the business cares about leads/revenue.
- Overexplaining match types when the client only needs the decision.

# Daily Ads Operator

Use this loop when the user asks for a recent-day check, morning brief, "today's keywords", or ongoing account management. The goal is a concise operator note with an approval queue, not a dashboard dump.

## Contract

Every daily operator pass must:

- Identify the account, campaign scope, timezone, and reporting window.
- Compare the most recent complete day against a 7-day baseline; include today partial only when the user asks for same-day cleanup.
- Pull enough data to explain spend: campaign, ad group, keyword, search term, conversion action, impression-share, network, and recent change context when available.
- Classify the next step as **no action**, **watch**, **recommend**, or **needs approval**.
- Surface budget pacing/anomaly risk before recommending budget changes.
- Check pending interventions from prior changes and call out reviews due now.

## Data to pull

Choose the smallest useful set of available reads:

- Account setup / conversion actions via `summarizeAccountSetup` or GAQL.
- Campaign metrics for yesterday, last 7 days, and last 30 days when volume is low.
- Keyword and search-term metrics for the active scope.
- Impression-share fields for Search campaigns: budget lost vs rank lost.
- Network/device/date segmentation when CPA/CVR shifted.
- Recent account change history when explaining a regression.
- Active experiments/interventions when available.

## Output shape

```text
Scope: <account/campaign> / <window> / <timezone>
Top finding: <one sentence>

Snapshot:
- Spend:
- Clicks:
- Conversions / leads:
- Avg CPC / CPA:
- Pacing:

Read:
- <why the metrics moved, with denominator>

Watch:
- <entity> — trigger: <threshold/date>

Recommended actions:
1. <exact action>
   Evidence:
   Risk:
   Approval:

Pending reviews:
- <prior change> — due/too early/verdict
```

## Decision rules

- Thin data is a result. If the account has only 1–3 clicks, prefer watch conditions over hard mutations unless intent is clearly bad.
- Do not recommend a budget increase when spend is below budget and lost impression share to budget is low; diagnose rank, relevance, tracking, or demand instead.
- For Maximize Clicks accounts, treat cheap traffic as discovery, not success. Look for activation/lead quality before scaling.
- For local-service accounts, expensive `near me` clicks can be plausible exploration. Require intent mismatch or a spend threshold before pausing.
- For SaaS/product-led accounts, generic curiosity terms are usually lower quality than named-tool / problem-aware intent.
- Any proposed write must be handed to the safe executor pattern; do not execute from the daily brief without explicit approval.

## Budget pacing guard

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: 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:

- Overspend spike + no conversion signal: recommend tightening search terms / bids / schedule before increasing budget.
- Under-delivery + high lost IS rank: relevance/rank problem, not a budget problem.
- Under-delivery + low impressions: demand, geo, eligibility, or tracking issue.
- Healthy CPA + high lost IS budget: budget increase can be proposed, still approval-gated.

## Anti-patterns

- Raw GAQL row dumps.
- Recommending budget increases before checking conversion tracking and impression-share split.
- Pausing strategic broad keywords before checking exact/phrase safety nets.
- Treating CTR or CPC as success without conversion or business-quality context.

# 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.

# 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.

# External Benchmarks and Forecasts

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.

## 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.

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.

## 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.

## If an external benchmark is necessary

Record:

- 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.

Label the result **external directional context**. Do not authorize a bid, budget, pause, or restructure solely from it.

## Current Google anchors

Checked 2026-09-09:

- [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)

These tools remain model-based. Validate material decisions with mature business outcomes and experiments where feasible.

# Intervention Memory

Use this whenever the agent recommends or executes a material Google Ads change. The goal is to make future reviews measurable instead of anecdotal.

## Intervention record

Store or report enough detail for a future 3/7/14-day review:

```json
{
  "id": "<stable id or changeId group>",
  "created_at": "<ISO>",
  "account_id": "<account>",
  "scope": { "campaign_id": "", "ad_group_id": "", "entity_ids": [] },
  "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": "<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>",
  "status": "watching"
}
```

Use durable change history or intervention tracking when the live connection
supports it. Choose available capabilities for recording the change and comparing
outcomes; do not assume that every operation is automatically logged.

If the environment lacks durable intervention storage, include the record in the session report and recommend persisting it before scheduling automated reviews.

## Review protocol

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.
3. Check confounders: other changes, budget shifts, seasonality, tracking edits.
4. Classify verdict:
   - likely positive
   - likely negative
   - neutral/inconclusive
   - too new / insufficient data
5. Decide: keep, revert, iterate, or extend watch.

## Output shape

```text
Impact review — <change>
Verdict: likely positive / inconclusive / negative

Baseline: <window>
After: <window>
Metric movement:
- CPA:
- Waste spend:
- Conversions:
- Guardrail:

Confounders:
Decision:
```

## Anti-patterns

- Reviewing raw spend without denominators.
- Calling a change successful when conversion volume is too low.
- Ignoring other edits in the same campaign during the window.
- Forgetting to define success before making the change.

# Quality Score Diagnostic

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

Quality Score is shown on a 1–10 scale with three historical comparison components:

- expected click-through rate;
- ad relevance;
- landing-page experience.

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.

## Diagnostic sequence

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

- **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.

## Prioritization

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.

## Current Google anchor

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.

# Repeatable Optimization Loops

This reference turns the generalized paid-search patterns in `../../shared/ppc-optimization-pattern-playbook.md` plus NotFair/Tong operating patterns into reusable Google Ads workflows. Use it when the user asks for recurring improvement, daily/weekly checks, campaign cleanup, or "what should I do next?"

Core principle: **diagnose the bottleneck before changing the account.** Most failed optimizations come from treating symptoms — low conversions, high CPA, limited spend — without separating measurement, query quality, rank, budget, ad message, and landing-page fit.

---

## Loop 1 — Daily / recent-day keyword and search-term check

Use for: "check today's keyword", "what spent today", "overview and proposal", small-account monitoring, post-change watch.

### Pull once

Use available read capabilities and batch related data when useful. Consider:

- Campaign metrics for today, yesterday, 7d, and 30d.
- Keyword metrics for the active/recent day.
- Search terms for the active/recent day.
- Campaign budgets, bidding strategy, search lost IS budget/rank, top IS / absolute top IS where available.
- Recent account change history for context.

### Interpret

Report in this order:

1. **Evaluated** — spend, clicks, impressions, conversions, avg CPC, CTR, and whether the campaign is enabled/serving.
2. **Changed** — what was changed recently, or "nothing today".
3. **Saw** — 1–3 concrete search-term / keyword observations.
4. **Proposal** — either a small action or "no change proposed yet".

### Decision rules

- 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.
- Budget-limited with good CPA: budget increase can be reasonable, but first verify marginal query quality and search partners.

Tong-facing output should be short, like an operator note — not a full audit.

---

## Loop 2 — Search-term → n-gram → action buckets

Use for: wasted spend, add negatives, broad match cleanup, low conversion quality, PMax/Search overlap.

### Pull once

Search term data for 30–90 days by campaign/ad group/network:

- search term, campaign/ad group, keyword where available
- cost, clicks, impressions, conversions, conversion value
- network segment if available
- campaign type / bidding strategy

### Aggregate

Inside the script, tokenize search terms into 1-, 2-, and 3-grams. For each n-gram capture:

- total cost, clicks, impressions, conversions, CPA / ROAS
- distinct search terms, campaigns, ad groups
- example queries by spend
- whether the n-gram appears in existing positives or negatives

### Action buckets

Do not output one raw list. Classify:

1. **Negative candidates** — irrelevant intent, wrong geography, job seeker, DIY/info, free/cheap when not offered, competitor/name-seeking when not intentionally conquesting.
2. **Keyword candidates** — converting search terms not present as exact/phrase positives.
3. **Routing candidates** — same query/n-gram served by multiple ad groups with materially different CPA/CVR.
4. **Ad / landing-page mismatch** — relevant query, poor performance, weak message match or QS component.
5. **Product / content opportunity** — repeated relevant demand the business does not currently target or sell.

### Safeguards

- Never negative a brand/protected/core service term without explicit user confirmation.
- Check positive-keyword and high-value search-term conflicts before adding negatives.
- Prefer shared negative lists for universal disqualifiers; use campaign/ad-group negatives for routing.
- Negative match variants matter: plurals, misspellings, and close variants are not as forgiving as positive keywords.
- Treat high-spend/no-conversion n-grams as review triggers, not automatic negatives.

---

## Loop 3 — Budget / impression-share triage

Use for: "raise budget", "limited by budget", "not spending", "more conversions", "rank loss", "why did conversions drop?"

### Pull once

Campaign-level:

- cost, clicks, impressions, conversions, CPA / ROAS for 7d, 30d, and prior comparable window
- daily budget and actual daily spend
- search impression share, lost IS due to budget, lost IS due to rank, top IS, absolute top IS
- bidding strategy, target CPA/ROAS, learning/primary status if available
- search-term quality and network split
- recent changes

### Classify the blocker

- **Budget-constrained:** spend reaches budget and lost IS budget is material.
- **Rank-constrained:** spend is below budget and lost IS rank is material.
- **Demand-constrained:** low impressions with low lost IS; market/search volume is limited.
- **Quality-constrained:** rank loss plus weak QS/ad relevance/LPX.
- **Query-quality constrained:** spend scales into irrelevant/non-converting terms.
- **Tracking-constrained:** conversion signal is broken or inconsistent.

### Recommendation rules

- Lost IS budget near zero → budget increase is unlikely to help.
- Spend far below budget + high rank-lost IS → improve relevance / landing page / bid competitiveness before increasing budget.
- Budget-limited + profitable CPA/ROAS + clean search terms → propose a measured budget increase within guardrails.
- Budget-limited + broad/search-partner waste → clean traffic first; more budget will scale waste.
- PMax overlap can distort Search impression share. Check PMax/Search term overlap before declaring Search demand missing.

---

## Loop 4 — Broad match readiness and containment

Use for: "should we use broad", Google recommendations, scaling a campaign, broad match waste.

### Readiness gate

Broad match is only testable when most of these are true:

- Conversion tracking is trustworthy and primary actions match the business goal.
- The campaign has enough conversion volume for automated bidding to learn.
- Budget can absorb exploration without starving proven exact/phrase terms.
- Landing pages are focused enough that broader query intent still receives a relevant page.
- Existing search-term review cadence and negative/shared-list hygiene exist.
- The campaign is not a very short buying-cycle / tiny-budget / weak-signal account where every bad click hurts.

### Safer rollout

- Prefer experiment or limited ad-group rollout over account-wide broad expansion.
- Pre-build obvious negatives and brand/geography controls.
- Monitor query mix, CPA/ROAS, CTR, CVR, and incremental conversions against exact/phrase baseline.
- Do not assume exact always beats broad; with strong Smart Bidding, broad can sometimes find better converting auctions. Keep what wins on business metrics.

---

## Loop 5 — Conversion tracking integrity before optimization

Use for: first audit, CPA/ROAS seems wrong, Smart Bidding, offline conversions, low-volume client accounts.

Before aggressive bid/budget/keyword decisions, verify:

- At least one relevant primary conversion action is enabled.
- Lead-gen uses one-per-click counting unless there is a clear reason not to.
- Purchase/value accounts have sane values and currency.
- Imported/read-only actions are understood before trying to mutate them.
- Campaign-specific goals do not accidentally optimize for irrelevant actions.
- Duplicate tags/actions are not double-counting.
- Phone, form, and offline conversion coverage matches how leads actually close.

If tracking is materially broken, stop. Fix measurement first; do not optimize bidding on bad signal.

---

## Loop 6 — Small client-account posture

This captures the pattern from CentsIQ-style accounts: expensive clicks, low volume, high need for message match.

- Use exact/phrase and clean query review before broad exploration.
- Do not jump to Smart Bidding or budget increases just because volume is low.
- If spend is far below budget, inspect rank loss and Quality Score before touching budget.
- For high-CPC lead gen, a single bad competitor/info click matters. Daily notes should propose small negatives only when the intent is clearly wrong.
- Landing page clarity and trust can be the highest-leverage change when query intent is clean but clicks do not convert.

---

## Sources

- `../../shared/ppc-optimization-pattern-playbook.md`
- Generalized paid-search operations: n-gram analysis, negative keyword hygiene, broad match readiness, RSA testing, Quality Score, impression share, conversion tracking, Search Partners, landing-page testing, and audit automation patterns.

# Safe Executor

Use this pattern for every Google Ads write. It is the gatekeeper between recommendations and mutations.

## Contract

Before any write:

- Verify actor, account, campaign/ad group/ad/keyword target, scope, and blast radius.
- Confirm the exact current state and exact desired state.
- Confirm the user approved the specific write or an explicitly bounded batch.
- Check active experiments; either apply consistently to both arms or require explicit experiment-impact acknowledgement.
- Prefer reversible / low-risk changes first.

After any write:

- Capture `changeId` and tool response.
- Verify the exact changed resource with a fresh read against the relevant resource type.
- Report verified live state, not just the mutation response.
- If verification fails, say the write is unverified/failed and do not claim success.

## Approval text

For approval queues, make the user able to answer with `approve 1`, `approve all low risk`, or `explain 2`.

```text
Needs approval:
1. Add phrase negative `jobs` to Campaign X
   Current state: not present
   Proposed state: campaign-level phrase negative
   Evidence: $42 spend, 0 conv, employment intent
   Risk: low — blocks job-seeker traffic only
   Verification: read campaign negatives after write
```

## Preflight checklist

- Account ID/name resolved.
- Campaign/ad group/ad/criterion IDs resolved.
- Parent statuses are not removed.
- Change does not touch an active experiment unless handled intentionally.
- Guardrails permit the change size.
- Keyword pause/bid/budget changes are within user-approved blast radius.
- Negative keywords do not conflict with strategic positive intent.
- RSA updates include complete headline/description replacement if required by the tool.

## Verification checklist

Use the narrowest read that proves the state:

- Negative keyword write → read campaign/ad-group/shared-set negatives.
- Positive keyword add/pause → read the current keyword criterion status and match type.
- Bid/budget write → read campaign/ad group/keyword bidding field.
- RSA update → read `ad_group_ad` responsive search ad assets.
- Asset link/unlink → read asset links.
- Experiment schedule/promote → call async error list after the long-running operation.

## Failure handling

- A NotFair `changeId` for a failed operation is an attempted-change log, not proof of Google acceptance.
- Preserve Google request IDs, enum names, and partial-failure details when available.
- Compare nearby successful writes to distinguish account auth, tool routing, resource policy, and request-shape problems.
- Use dry-run / validate-only probes when available before retrying a risky mutation.
- File internal NotFair tool feedback when the tool returns misleading success semantics or an unhelpful error surface.

## Anti-patterns

- Saying "done" before a live read verifies the state.
- Treating all `authorization_error=7` as global auth failure when other write types succeeded.
- Retrying the same failed mutation repeatedly without changing hypothesis.
- Hiding partial failures in a bulk operation.

# Search-Term Analysis Guide

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

For the chosen complete window, retain:

- 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.

Search-term reporting may not expose every query. State coverage limits instead of treating the table as the full universe.

## Aggregate before acting

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.

Classify into:

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.

## Negative-keyword safety

- 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.

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

Exact, phrase, and broad describe progressively wider semantic reach. Their performance cannot be compared fairly without reconciling query mix, bidding, routing, goals, and maturity.

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.

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

Return:

- 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.

## Current Google anchors

Checked 2026-09-09:

- [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)

Re-verify current platform behavior when the decision depends on it.

# Search-Term Triage

Use this when the user asks to clean keywords/search terms, add negatives, review broad match, or inspect today's traffic quality.

## Contract

Search-term triage produces a small, approval-ready action queue. It must classify each pattern before proposing a write.

## Action buckets

- **Negative candidate** — clearly non-buyer, wrong service, job/training/research/free-template, irrelevant brand/tool, competitor lookup that the advertiser should not buy.
- **Keyword candidate** — relevant converting or high-intent term not already covered by exact/phrase.
- **Routing candidate** — relevant query is serving in the wrong campaign/ad group or landing page.
- **Ad/LP mismatch** — query is relevant but poor CVR/Quality Score suggests the message chain is weak.
- **Watch** — plausible buyer intent with too little data.
- **Winner** — term deserves more budget/coverage once economics are proven.

## Required checks before negatives

1. Aggregate by n-gram/token pattern, not just individual terms.
2. Check whether the term conflicts with any enabled positive keyword or strategic service line.
3. Check match type and scope: campaign-level negative vs shared list vs ad-group negative.
4. Prefer exact/phrase negatives when blocking a narrow leak; broad negatives only for unmistakably bad concepts.
5. Preserve converting terms and high-intent local/service terms unless the user explicitly chooses to stop buying that demand.

## Local-service examples

Usually negative:

- jobs, salary, career, training, course, certification, apprenticeship
- free template, DIY, software-only, calculator-only
- services the business does not sell
- locations outside the service area

Usually watch first:

- `service near me`
- `service city`
- competitor-adjacent terms where intent may still be commercial
- high-CPC local terms with 1–3 clicks and no conversions

Usually promote:

- Service + city/neighborhood terms with conversions.
- Search terms that mirror the best landing-page offer.

## SaaS/Product-led examples

Usually negative:

- free no signup, tutorial, meaning, what is, course, jobs, salary
- unrelated tools/products surfaced by broad match
- generic marketplace/list/directory terms when the product is not a directory

Usually promote:

- product category + named workflow
- named integration + problem
- competitor/integration terms only when landing page and brand framing are clear

## Output shape

```text
Search-term triage — <scope/window>

Waste patterns:
- <n-gram/pattern>: spend/clicks/conversions, recommendation

Approval queue:
1. Add <match type> negative `<term>` at <scope>
   Reason:
   Conflict check:
   Risk:

2. Add exact/phrase keyword `<term>` to <ad group>
   Reason:
   Landing page:
   Risk:

Watch:
- <term/entity> until <threshold>
```

## Anti-patterns

- Adding a negative solely because a term has zero conversions on tiny click volume.
- Blocking a high-value service category because one broad keyword is noisy.
- Adding broad negatives without checking conflicts.
- Mixing recommendations and writes in the same step without explicit approval.

# Session Start Checks

Run these checks when the user's request is analysis-oriented (performance reviews, optimization, "how are my ads", "show me", audits) OR when the user explicitly asks to review their changes ("check my changes", "did my changes work"). Skip them for direct action commands like "pause keyword X", "rename campaign Y", "add negative keyword Z".

## Check for pending change reviews

Read `{data_dir}/change-log.json`. Find entries where `reviewed` is `false`.

**If unreviewed changes exist but `reviewAfter` has NOT passed yet:**

> **Changes still maturing:**
>
> _[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 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 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 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 [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
{
  "reviewed": true,
  "reviewedAt": "<ISO 8601>",
  "reviewResult": {
    "afterSnapshot": { "spend7d": 0, "conversions7d": 0, "cpa7d": 0, "ctr7d": 0 },
    "assessment": "positive|negative|inconclusive",
    "note": "<one line summary>"
  }
}
```

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 anomalies

Read `{data_dir}/account-baseline.json`. If it exists AND was last updated >24 hours ago:

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).

If `account-baseline.json` doesn't exist, skip — it will be created at session end.