Open-source SEO, GEO, and marketing skills for AI agents.
Add Google Ads operator playbooks
Tong Chenc56cdf92961a
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonindex f4cf073b..3bf131c7 100644--- a/.claude-plugin/marketplace.json+++ b/.claude-plugin/marketplace.json@@ -5,14 +5,14 @@},"metadata": {"description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO, GEO, Google Ads, and Meta Ads skills for Claude Code.",- "version": "0.25.4"+ "version": "0.25.5"},"plugins": [{"name": "notfair","source": "./","description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO analysis, Google Ads management, Meta (Facebook + Instagram) Ads management, GSC-driven content planning + local calendar viewer, keyword research, content optimization, schema markup, meta tags optimization, broken link checker, single-page deep audit, and Generative Engine Optimization for AI search.",- "version": "0.25.4",+ "version": "0.25.5","author": {"name": "NotFair","url": "https://notfair.co"diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex ea689528..55b6da58 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "notfair",- "version": "0.25.4",+ "version": "0.25.5","description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO analysis, Google Ads management, Meta (Facebook + Instagram) Ads management, keyword research, content optimization, schema markup tools, broken link checker, single-page deep audit, and Generative Engine Optimization (GEO) for AI search engines — powered by Google Search Console, Google Ads, and Meta Marketing APIs.","author": {"name": "NotFair",diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 5dfacb72..28941957 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -11,6 +11,20 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).---+## [0.25.5] — 2026-05-28++### Added++- Added Google Ads operator references for daily briefs, search-term triage, safe MCP execution, intervention memory, client reporting, local lead-gen accounts, and SaaS/B2B product-led accounts.+- Added Google Ads management evals covering daily operator briefs, safe search-term cleanup, failed mutation handling, and NotFair-style SaaS activation optimization.++### Changed++- Expanded Google Ads skills with repeatable optimization loops for search-term/n-gram triage, budget/rank diagnosis, broad match containment, RSA testing, landing-page message-chain testing, and conversion/network integrity checks.+- Updated `/google-ads` routing guidance to use the new daily operator, safe executor, intervention memory, and domain playbook references for recurring account-management workflows.++---+## [0.25.4] — 2026-05-28### Changeddiff --git a/VERSION b/VERSIONindex 35aa2f3c..16c6b58f 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-0.25.4+0.25.5diff --git a/google-ads/audit/SKILL.md b/google-ads/audit/SKILL.mdindex ebd318f5..a3a3b3c2 100644--- a/google-ads/audit/SKILL.md+++ b/google-ads/audit/SKILL.md@@ -45,6 +45,7 @@ You decide the exact GAQL shape, but a defensible audit needs to see, at minimum- Search terms (`search_term_view`)- Negative keywords and shared lists (`campaign_criterion` + shared sets)- Conversion actions (`conversion_action`) — including counting type, attribution model, primary/secondary+- Network segmentation (`segments.ad_network_type`) when diagnosing CPA/CVR shifts or Search Partners- RSA assets (`ad_group_ad`)- Geo targeting (`campaign_criterion` LOCATION + PROXIMITY)- Recent change events (`change_event`, last 30 days) — for explaining regressions@@ -80,6 +81,8 @@ To compute and back the pulse metrics, you'll need to look across these seven ar6. **Impression Share** — read rank-lost vs budget-lost together (see the 2×2 matrix in `account-health-scoring.md`); they're different problems with different fixes.7. **Spend Efficiency** — waste vs. headroom, brand vs. non-brand split, concentration risk.+For Signal Quality and network-mix questions, read `references/conversion-network-audit.md`. It adds the prerequisite checks for conversion-action integrity, Search Partners, Display leakage in Search campaigns, and regression decomposition.+Per-area findings only show up in the report when the area surfaced something material. Cite specific entities, dollars, and time windows. "Some keywords are underperforming" is not a finding; "Campaign X has $1,840 in last-30-day spend on 12 keywords with 0 conversions and QS ≤ 4" is.For unit-economics-aware framing: if `business-context.json.unit_economics.aov_usd` and `profit_margin` exist, frame waste and headroom in dollars saved / captured per month, not "above account average". See `../shared/ppc-math.md`.diff --git a/google-ads/audit/references/conversion-network-audit.md b/google-ads/audit/references/conversion-network-audit.mdnew file mode 100644index 00000000..915a856f--- /dev/null+++ b/google-ads/audit/references/conversion-network-audit.md@@ -0,0 +1,69 @@+# Conversion + Network Integrity Audit++Use this during first-time audits, regression explanations, Smart Bidding/budget recommendations, Search Partners questions, or any account where CPA/ROAS looks suspicious.++Bid, budget, negative, and ad-test decisions are only as good as the conversion and traffic segment data behind them. Measurement and network mix are prerequisite checks, not afterthoughts.++---++## 1. Conversion tracking integrity++Pull conversion-action inventory and campaign conversion settings before recommending aggressive optimization.++Check:++- Enabled primary conversion actions exist and match the business goal.+- Lead-gen counting is normally `ONE_PER_CLICK`; purchases/subscriptions may be `MANY_PER_CLICK`.+- Conversion values/currencies are present and sane when using value-based bidding.+- Imported/read-only actions are not treated as mutable API targets.+- Campaign-specific goals do not optimize one campaign for irrelevant actions.+- Duplicate actions/tags are not double-counting the same event.+- Offline/call/form coverage matches how revenue actually happens.+- Recent zero-conversion cliffs are not caused by tag/site/form changes.++Stop condition:++- If tracking is materially broken, say so and recommend fixing measurement before bid/budget changes. Do not optimize on bad signal.++---++## 2. Network segmentation++Use for Search Partners, Display-in-Search leakage, unexplained CPA/CVR shifts.++Pull by `segments.ad_network_type` when compatible:++- cost, clicks, impressions, conversions, conversion value+- CTR, CVR, CPA/ROAS+- campaign/ad group+- search terms where available++Interpretation:++- **Google Search better, Partners material and worse:** recommend disabling Search Partners or testing without them.+- **Partners better or similar:** keep, but monitor because partner mix is opaque and can shift.+- **Tiny partner volume:** do not overreact.+- **Display Network in Search campaign:** flag as structural leakage unless intentionally enabled.++Search Partners decision must be based on the account's goal metric, not CTR alone. A lower CTR partner segment can still be profitable; a high CTR segment can still produce junk leads.++---++## 3. Regression lens++When conversions or CVR change, split the diagnosis:++- Traffic volume changed: impressions/clicks/search demand/impression share.+- Traffic quality changed: search terms, network, match type, geography/device.+- Conversion rate changed: landing page, tracking, form, offer, site speed.+- Bidding changed: strategy, targets, learning, budget caps.+- Measurement changed: conversion actions, primary flags, tag health, offline import.++Always overlay recent changes from NotFair changes and Google `change_event` before attributing causality.++---++## Sources++- `../../shared/ppc-optimization-pattern-playbook.md` — conversion tracking, Search Partners, and conversion-change diagnosis modules.+- General conversion tracking, Search Partners evaluation, assisted conversions, and KPI monitoring patterns.diff --git a/google-ads/copy/SKILL.md b/google-ads/copy/SKILL.mdindex e1b15d0b..1aef7db9 100644--- a/google-ads/copy/SKILL.md+++ b/google-ads/copy/SKILL.md@@ -17,6 +17,7 @@ Read and follow `../shared/preamble.md` (MCP detection, account selection) and `Read on demand:- `references/rsa-best-practices.md` — character limits, headline formulas, pinning, A/B mechanics, common mistakes. The source of truth for what to write.+- `references/rsa-testing-lab.md` — how to choose RSA test metrics, diagnose ad-group intent bloat, decide pinning, and avoid chasing Ad Strength over business outcomes.- `../manage/references/industry-benchmarks.md` — industry CTR/CVR benchmarks for sanity-checking targets.- `../manage/references/quality-score-framework.md` — only when QS improvement is the explicit goal.@@ -68,6 +69,8 @@ When the user wants to test, use the MCP server's experiment tooling rather thanEach variant must test a **meaningfully different angle** — not word swaps. "Trust & Expertise" vs. "Speed & Convenience" vs. "Price & Value" is a real test; "Call Today" vs. "Call Now" is noise.+Before writing variants, read `references/rsa-testing-lab.md` when the request mentions testing, pinning, Ad Strength, low CTR/CVR, or mixed-intent ad groups. It encodes the generalized pattern that many RSA problems are really ad-group/query-theme problems.+When calling a winner, the underlying question is the same regardless of mechanism: did the variant win on conversion rate (or CPA), backed by enough sample to trust the difference? Less than ~100 clicks per variant is too early. ≥20% relative CTR or CVR delta is meaningful. 2× CVR gap is decisive immediately. The experiments framework's own significance signals are the cleanest input — defer to them when present.After a winner: pause the loser, then iterate against the winner. Never stop testing.diff --git a/google-ads/copy/references/rsa-testing-lab.md b/google-ads/copy/references/rsa-testing-lab.mdnew file mode 100644index 00000000..8c43203d--- /dev/null+++ b/google-ads/copy/references/rsa-testing-lab.md@@ -0,0 +1,116 @@+# RSA Testing Lab++Use this when the user asks to improve CTR, write/test RSAs, pin headlines, compare ad variants, or diagnose ad groups with mixed intent. It complements `rsa-best-practices.md`: that file tells you how to write compliant assets; this file tells you how to decide what to test and when to trust the result.++---++## 1. Choose the test objective first++Google's Ad Strength and asset labels are not the business objective. Pick the winner metric before generating copy:++- **CTR** — when the bottleneck is low click-through and the landing page converts normally.+- **CVR** — when traffic volume is acceptable but query/ad/page promise may be wrong.+- **CPA** — lead-gen default when conversion volume is enough.+- **ROAS / conversion value per impression** — e-commerce or value-tracked accounts.+- **Conversion per impression (CPI)** — useful when both CTR and CVR can move; it rewards ads that create conversions from available impressions.++If data is thin, state that the test is directional. Do not call winners from tiny conversion samples.++---++## 2. Diagnose ad-group organization before writing++The biggest RSA failure is often not the words — it is putting too many query intents into one ad group, then asking one RSA to match all of them.++Before writing:++1. Pull recent search terms for the ad group.+2. Cluster them by intent: service, location, urgency, price, competitor, problem/pain.+3. Compare clusters to the final URL and current RSA assets.+4. If one ad group contains materially different intents, recommend splitting before writing more assets.++Examples:++- `bookkeeping seattle`, `quickbooks cleanup`, and `tax prep` may need different RSAs/pages.+- `Claude MCP server`, `Codex MCP`, and generic `AI agent for Google Ads` may need separate NotFair messaging and negatives.++---++## 3. Test real angles, not word swaps++Good tests compare distinct hypotheses:++- **Trust / proof:** reviews, years, certifications, named expertise.+- **Speed / convenience:** same-day, fast setup, easy process.+- **Price / value:** transparent pricing, starting price, fixed-fee plans.+- **Pain / problem:** messy books, wasted ad spend, low-quality leads.+- **Local / specificity:** city/service fit, neighborhood intent.+- **Brand clarity / safety:** independent, approval-gated, not affiliated language where needed.++Bad tests:++- `Call Today` vs `Call Now`.+- Adding many generic headlines just to chase Excellent Ad Strength.+- Writing assets for intents not present in the ad group's search terms.++---++## 4. Pinning decision rules++Pinning can reduce Google's Ad Strength but improve business outcomes when message control matters.++Pin when:++- Legal/compliance/brand clarity must always appear.+- The ad group is narrow and one service/location promise should anchor every ad.+- The campaign has Limited Ad Serving / trust ambiguity and the brand must be explicit.+- The landing page headline requires the ad's promise to match word-for-word.++Avoid heavy pinning when:++- Query intent varies widely and Google needs room to compose.+- You are using RSAs to discover which value prop resonates.+- You do not have enough volume to test pinned vs unpinned.++Default controlled structure:++- Pin one service/location or brand-clarity headline to `HEADLINE_1` only when needed.+- Optionally pin one CTA to `HEADLINE_3`.+- Leave `HEADLINE_2` unpinned for value prop / trust / pain-angle testing.++---++## 5. Experiment mechanics++Preferred paths:++- Use `createAdVariationExperiment` for clean RSA asset tests.+- Use `createExperiment` + arms for broader ad+landing-page or structural tests.+- For very low-stakes / low-volume work, before/after can be acceptable, but report confounders.++Minimum-read rules:++- <100 clicks per variant: usually too early for CTR/CVR conclusions.+- ≥20% relative CTR/CVR delta: meaningful directional signal if volume is reasonable.+- 2x CVR gap: strong signal, still check conversion count and recent changes.+- If the test changes final URL, evaluate both CTR and CVR; an ad can win clicks while losing leads.++---++## 6. Output shape++For copy proposals, show:++- Baseline problem: entity + metric + window.+- Test hypothesis: what angle should improve and why.+- Complete RSA assets with character counts.+- Pinning plan, if any.+- Winner metric and minimum read threshold.+- Exact mutation path, but wait for user approval before writing.++---++## Sources++- `../../shared/ppc-optimization-pattern-playbook.md` — RSA/ad testing module.+- General RSA testing, ad testing metrics, ad group organization, Ad Strength, and ad+landing-page testing patterns.diff --git a/google-ads/landing/SKILL.md b/google-ads/landing/SKILL.mdindex 1550c077..2b79ec6d 100644--- a/google-ads/landing/SKILL.md+++ b/google-ads/landing/SKILL.md@@ -14,9 +14,12 @@ Google Ads campaigns fail on the landing page more often than in the auction. AOnly score pages that actually run ad traffic. Don't score random marketing pages. Run this on direct request, on auto-handoff from `/google-ads-audit` (high-CTR / low-CVR ad groups), when QS diagnosis flags "Landing Page Experience: Below Average", or as a preflight before `/google-ads-copy` writes new copy for a page nobody's validated.+When the question is about ad-to-page fit, high CTR / low CVR, LPX, or testing ads and landing pages together, read `references/message-chain-testing.md` before scoring. It keeps the diagnosis focused on the paid-search message chain instead of drifting into a generic web-design audit.+## Reference- `references/scoring-rubric.md` — the 5-dimension weighted rubric, thresholds, and evidence fields. Read before scoring.+- `references/message-chain-testing.md` — query → ad → page message-chain diagnosis and ad+LP test design.- `../manage/references/quality-score-framework.md` — only when the user's explicit goal is QS improvement.## Phase 1: Resolve the target pagesdiff --git a/google-ads/landing/references/message-chain-testing.md b/google-ads/landing/references/message-chain-testing.mdnew file mode 100644index 00000000..e9eceaf3--- /dev/null+++ b/google-ads/landing/references/message-chain-testing.md@@ -0,0 +1,96 @@+# Ad + Landing Page Message-Chain Testing++Use this when landing-page experience, high CTR / low CVR, Quality Score LPX, or ad-copy testing points to a mismatch between the query, ad, and landing page.++Core idea: sometimes you are not testing an ad or a page in isolation — you are testing a **message chain**. Query intent → RSA promise → landing-page headline/offer/form must reinforce one another.++---++## 1. Map the message chain++For each target ad group or URL, collect:++- Top search terms and converting terms.+- Active RSA headlines/descriptions and pinned assets.+- Final URL, H1, hero subheadline, CTA, form fields, trust proof.+- Keyword QS components if available, especially ad relevance and landing-page experience.+- Last 30d clicks, spend, CTR, CVR, conversions, CPA/ROAS.++Then classify:++- **Match:** query phrase, ad promise, and page H1/offer use the same concept.+- **Drift:** same general business, but page does not reinforce the exact promise.+- **Broken:** ad promises one thing and page leads with another.++Examples:++- Query: `Seattle bookkeeping services`; ad: `Bookkeeping from $190/mo`; page H1: `Seattle & King County Bookkeeping Services` → strong match.+- Query: `QuickBooks cleanup`; ad: `QuickBooks Cleanup Help`; page H1: generic `Accounting Services` → drift.++---++## 2. Decide test design++### Ad-only test++Use when page is already tightly aligned and the bottleneck is CTR/ad relevance.++### Landing-page-only test++Use when ads are clear and CTR is healthy, but CVR / LPX / form friction is weak.++### Paired message-chain test++Use when the angle changes both ad and page promise, e.g.:++- `Free bookkeeping review` ad → page hero and form explicitly offer the review.+- `QuickBooks cleanup` ad → page hero, proof, FAQ, and CTA are cleanup-specific.+- `NotFair for Claude MCP` ad → page hero clarifies NotFair + Claude/Codex/OpenClaw compatibility.++### Full factorial ad × page test++Use when you need to know whether the ad, page, or their combination drives the win. This requires enough traffic and clean tracking; otherwise it creates noise.++---++## 3. What to fix first++Prioritize by evidence:++1. **Broken message match** — update H1/hero/CTA or rewrite RSA to match the page.+2. **Missing trust proof** — add reviews, local proof, certifications, price transparency, client type, examples.+3. **Form friction** — reduce fields, clarify what happens next, make CTA specific.+4. **Mobile/page speed** — if PSI or manual browser evidence shows slow LCP/interaction problems.+5. **Offer ambiguity** — if the ad says free/review/quote but the page hides or dilutes it.++Do not redesign the entire page when a specific above-the-fold message change would fix the paid-search problem.++---++## 4. Reporting format++Lead with the concrete chain:++- Search term theme: `<actual query/theme>`+- Top ad promise: `<headline/description>`+- Page H1 / CTA: `<actual text>`+- Verdict: Match / Drift / Broken+- Fix first: `<single above-the-fold change>`+- Why: `<metric + window>`++For small accounts, keep recommendations conservative. One high-CPC click can look dramatic; the right proposal may be "watch for 3–5 more relevant clicks" if traffic is clean but sample is tiny.++---++## 5. Mutation boundary++This skill diagnoses pages. If the repo/site is available and the user asks for local page edits, make the smallest page change and verify with browser screenshots / HTML checks. If only Google Ads changes are needed, hand off to `/google-ads-copy` for RSA assets or `/google-ads` for final URL / experiment changes.++Always avoid form submissions unless explicitly approved; they can trigger client emails or CRM automations.++---++## Sources++- `../../shared/ppc-optimization-pattern-playbook.md` — landing page and ad+LP testing modules.+- General landing-page experience, ad+landing-page testing, customer-journey testing, and Quality Score patterns.diff --git a/google-ads/manage/SKILL.md b/google-ads/manage/SKILL.mdindex 072f3c29..f63cb9a1 100644--- a/google-ads/manage/SKILL.md+++ b/google-ads/manage/SKILL.md@@ -85,9 +85,16 @@ These live alongside this skill. Read on demand — not preemptively.| 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` |-| Search-term mining, negatives, n-gram analysis | `references/search-term-analysis-guide.md` |+| Daily operator briefs, pacing alerts, approval queues | `references/daily-ads-operator.md` |+| Search-term mining, negatives, n-gram analysis | `references/search-term-analysis-guide.md` + `references/search-term-triage.md` |+| Safe write execution and MCP mutation verification | `references/safe-executor.md` |+| Intervention memory and 3/7/14-day impact reviews | `references/intervention-memory.md` |+| Client-facing ads updates | `references/client-reporter.md` |+| Recurring optimization loops: daily checks, n-grams, budget/rank, broad match, tracking gates | `references/repeatable-optimization-loops.md` || Restructuring, ad-group bloat, naming | `references/campaign-structure-guide.md` || Reviewing prior changes for impact | `references/session-checks.md` + `references/change-tracking.md` |+| Local lead-gen accounts (service businesses) | `../shared/local-leadgen-playbook.md` |+| SaaS / B2B product-led acquisition | `../shared/saas-b2b-playbook.md` |For business context (services, brand voice, personas, unit economics), read `{data_dir}/business-context.json` and `{data_dir}/personas/{accountId}.json`. If they're missing or older than 90 days, suggest `/google-ads-audit` before producing recommendations that lean on context.@@ -124,3 +131,16 @@ After analysis, proactively offer the next skill when the data clearly points th- **Converting search terms not yet keywords (3+ conversions)** → offer to add them with `bulkAddKeywords`- **Impression-share decline tied to new competitor pressure** → pull `auction_insight_*` resources via GAQL- **Significant structural / bidding change considered** → propose an experiment (`createExperiment` + `addExperimentArms`) instead of a direct mutation, and let real traffic decide++## Recurring optimization posture++When the user asks for an ongoing/repeatable improvement pattern — "check today's keywords", "what should we do next", "keep improving this campaign", "clean up wasted spend", "should we scale?" — start with `references/daily-ads-operator.md`, then pull the narrowest supporting reference. The default posture is:++1. **Measure signal first** — conversion tracking, goal settings, recent changes, budget pacing, and pending intervention reviews.+2. **Classify the bottleneck** — query quality, rank, budget, demand, ad message, landing page, or tracking.+3. **Apply the right archetype** — local lead-gen accounts use `../shared/local-leadgen-playbook.md`; SaaS/B2B product-led accounts use `../shared/saas-b2b-playbook.md`.+4. **Triage search terms before scaling** — use `references/search-term-triage.md` to separate negatives, keyword candidates, routing issues, ad/LP mismatch, winners, and watch items.+5. **Propose the smallest reversible action** — usually a negative, exact keyword promotion, ad/LP message fix, or experiment; not a budget increase by reflex.+6. **Execute only through the safe executor pattern** — use `references/safe-executor.md`; approval and live read-back verification are mandatory.+7. **Record the intervention** — use `references/intervention-memory.md` so 3/7/14-day reviews can decide keep/revert/iterate.+8. **Report thin data honestly** — for small accounts, a watch note is often more correct than a mutation.diff --git a/google-ads/manage/evals/evals.json b/google-ads/manage/evals/evals.jsonindex 26ebe23f..7efa25aa 100644--- a/google-ads/manage/evals/evals.json+++ b/google-ads/manage/evals/evals.json@@ -40,6 +40,100 @@"Bid change recommendations stay within the 25% maximum guardrail","References impression share data in the analysis"]+ },+ {+ "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"+ ]}]}diff --git a/google-ads/manage/references/client-reporter.md b/google-ads/manage/references/client-reporter.mdnew file mode 100644index 00000000..f1f75bf0--- /dev/null+++ b/google-ads/manage/references/client-reporter.md@@ -0,0 +1,67 @@+# 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.diff --git a/google-ads/manage/references/daily-ads-operator.md b/google-ads/manage/references/daily-ads-operator.mdnew file mode 100644index 00000000..21ea1b80--- /dev/null+++ b/google-ads/manage/references/daily-ads-operator.md@@ -0,0 +1,88 @@+# 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++Prefer one `runScript` with `ads.gaqlParallel`:++- 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 change events or NotFair `getChanges` 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: yesterday spend > 150% of 7-day daily average or > 2x daily budget.+- Under-delivery: spend < 50% of budget while lost IS budget is low.++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.diff --git a/google-ads/manage/references/intervention-memory.md b/google-ads/manage/references/intervention-memory.mdnew file mode 100644index 00000000..335dfc1c--- /dev/null+++ b/google-ads/manage/references/intervention-memory.md@@ -0,0 +1,76 @@+# 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": "<CPA, CVR, waste spend, lead quality, QS, etc.>",+ "guardrail_metric": "<what must not degrade>",+ "baseline_window": "<date range>",+ "review_after_days": [3, 7, 14],+ "approval_source": "<chat/manual/standing rule>",+ "change_ids": [],+ "verification": "<verified live state>",+ "status": "watching"+}+```++Prefer NotFair server-side change/intervention surfaces when available:++- `getChanges`+- `listChangeInterventions`+- `getChangeIntervention`+- `evaluateChangeIntervention`+- `reviewChangeImpact`++If the environment lacks durable intervention storage, include the record in the session report and recommend persisting it before scheduling automated reviews.++## Review protocol++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.diff --git a/google-ads/manage/references/repeatable-optimization-loops.md b/google-ads/manage/references/repeatable-optimization-loops.mdnew file mode 100644index 00000000..ed18552f--- /dev/null+++ b/google-ads/manage/references/repeatable-optimization-loops.md@@ -0,0 +1,177 @@+# 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 one `runScript` / `gaqlParallel` pass. Include:++- 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 NotFair `getChanges` or Google `change_event` 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 data: if the day has <3 clicks or expected conversions <1, do not overfit. Say what you are watching for.+- 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.diff --git a/google-ads/manage/references/safe-executor.md b/google-ads/manage/references/safe-executor.mdnew file mode 100644index 00000000..d48643bc--- /dev/null+++ b/google-ads/manage/references/safe-executor.md@@ -0,0 +1,71 @@+# 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 `keyword_view` / `listKeywords` for 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.diff --git a/google-ads/manage/references/search-term-analysis-guide.md b/google-ads/manage/references/search-term-analysis-guide.mdindex 57f13349..fb921dca 100644--- a/google-ads/manage/references/search-term-analysis-guide.md+++ b/google-ads/manage/references/search-term-analysis-guide.md@@ -184,9 +184,22 @@ N-gram analysis identifies recurring word patterns in search terms to find syste### How to Run N-gram Analysis1. Export search term report (last 30-90 days)-2. Split each search term into individual words (unigrams) and word pairs (bigrams)-3. Aggregate clicks, cost, and conversions by each n-gram+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-gram4. 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)diff --git a/google-ads/manage/references/search-term-triage.md b/google-ads/manage/references/search-term-triage.mdnew file mode 100644index 00000000..39d1567a--- /dev/null+++ b/google-ads/manage/references/search-term-triage.md@@ -0,0 +1,89 @@+# 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.diff --git a/google-ads/shared/local-leadgen-playbook.md b/google-ads/shared/local-leadgen-playbook.mdnew file mode 100644index 00000000..72dfa7cf--- /dev/null+++ b/google-ads/shared/local-leadgen-playbook.md@@ -0,0 +1,56 @@+# Local Lead-Gen Playbook++Use this archetype for local service businesses such as pet care, bookkeeping, legal, home services, healthcare, and other location-bound lead-gen accounts.++## Core posture++Local-service accounts often have low volume, expensive clicks, and ambiguous `near me` intent. Optimize for qualified leads and booked revenue, not cheap traffic.++## Decision rules++- Do not overfit 1–3 expensive clicks when the query is plausibly high intent.+- Do not raise budget until conversion tracking, query quality, and impression-share constraints are understood.+- If lost impression share to budget is low and lost IS to rank is high, work on relevance/rank/landing page before budget.+- Preserve strategic services with controlled exact/phrase coverage before pausing broad-match discovery.+- Exclude non-buyer intent aggressively when unmistakable: jobs, salary, training, free templates, DIY, irrelevant service lines, out-of-area locations.+- Use client/business input for ambiguous adjacency, e.g. tax-adjacent bookkeeping leads or grooming vs boarding demand.++## Service-line protection++When a broad keyword for a core service is noisy:++1. Identify converting/high-intent search terms.+2. Add exact/phrase anchors for service + city/neighborhood.+3. Add only obvious irrelevant negatives.+4. Improve ad/landing-page message match.+5. Review after enough spend/clicks; then decide whether broad still earns its keep.++## Lead quality loop++Google Ads conversions are not enough. When possible, connect:++- lead form submissions+- phone calls+- booked consults/reservations+- closed customers+- revenue/LTV++Judge terms by qualified lead or booking quality once that data exists.++## Output priorities++For local accounts, reports should emphasize:++- spend by service/location intent+- expensive no-lead terms+- query relevance+- rank vs budget constraint+- lead quality questions+- next watch threshold++## Anti-patterns++- Killing a core service keyword before replacing it with exact/phrase coverage.+- Treating all zero-conversion local clicks as bad on tiny volume.+- Optimizing for CPC when high-value local leads are inherently expensive.+- Ignoring geography and service-area fit.diff --git a/google-ads/shared/ppc-optimization-pattern-playbook.md b/google-ads/shared/ppc-optimization-pattern-playbook.mdnew file mode 100644index 00000000..ad02c5b6--- /dev/null+++ b/google-ads/shared/ppc-optimization-pattern-playbook.md@@ -0,0 +1,213 @@+# PPC Optimization Pattern Playbook for NotFair Skills++Research date: 2026-05-29+Scope: generalized paid-search operating patterns distilled into reusable Google Ads workflows for NotFair skills.++## 1) Pattern inventory overview++- Coverage: search term management, n-grams, negatives, broad match, RSA/ad testing, Quality Score, bidding/budgets/impression share, conversion tracking, Search Partners, account audits, assets, landing pages, and PMax/Search overlap.+- Most reusable pattern families:+ - Search term + n-gram mining for negatives, new keywords, ad-group routing, and product/content insights.+ - Negative keyword hygiene: inconsistent coverage, conflicts, malformed terms, root-word negatives, and shared-list governance.+ - Broad match readiness and containment: only use when measurement, bidding, budgets, landing pages, and search-term review can support wider matching.+ - RSA testing: test business outcomes, not just Google ad strength/CTR; control ad-group granularity and pinning where message-to-query alignment matters.+ - Quality Score diagnosis: break down expected CTR, ad relevance, and landing-page experience; interpret trends with changes in ads, landing pages, targeting, budgets, and broad match expansion.+ - Impression share and budget/rank triage: separate lost IS due to budget from lost IS due to rank, then map to budget, bid, quality, asset, and targeting interventions.+ - Conversion tracking audit: validate action consistency before trusting automated bidding, ad tests, negative decisions, or budget scaling.+ - Search Partners evaluation: segment by network, compare profitability and search-term quality, then disable or split/monitor when partner traffic diverges.+ - Audit automation: automate deterministic checks first, escalate judgment-heavy findings with evidence and likely financial impact.+ - Landing-page experience and ad/LP testing: align message, trust, navigation, speed, and conversion action; test full message chains when ad and page interact.++## 2) Top repeatable patterns++1. **Aggregate before judging sparse queries**+ - Individual search terms often lack enough clicks for decisions. Roll up one-, two-, and three-token n-grams across queries, then sort by spend, clicks, conversions, CPA/ROAS, bounce-like engagement if available, and campaign/ad-group distribution.+ - Default candidate filters: `conversions = 0` sorted by cost; or high-click/no-conversion terms (example threshold: clicks > 150). Treat these as review triggers, not automatic negatives.++2. **Classify bad search terms by action, not just performance**+ - Irrelevant intent -> add negative keyword.+ - Relevant but wrong ad group/campaign -> add exact/phrase keyword to correct group and/or negative-route from wrong group.+ - Relevant but poor message fit -> rewrite RSA/landing page or split ad group.+ - Repeated relevant demand not sold/offered -> flag product/service/content opportunity.++3. **Use negatives as steering controls for automation**+ - Smart bidding and looser match types can keep spending on poor intent even after lots of clicks. Negatives are how the manager constrains the machine.+ - Watch question words, research phrases, consumer-vs-B2B modifiers, jobs/free/DIY, geography mismatch, and duplicated search terms served from lower-converting ad groups.++4. **Govern negative keyword scope deliberately**+ - Account-wide disqualifiers belong in shared negative lists linked consistently to campaigns.+ - Campaign/ad-group negatives should be reserved for routing, brand/non-brand separation, or product-line differences.+ - Audit for conflicts where a negative blocks a positive keyword or high-value search term.+ - Remember negative match types are not the same as positives: plurals/misspellings often require explicit variants.++5. **Broad match requires a readiness gate**+ - Before adding broad match, confirm conversion tracking is trustworthy, search-term management cadence exists, landing pages are focused, budget can absorb exploration, and bidding strategy fits the data volume/risk.+ - Prefer broad match for longer buying journeys or when smart bidding has meaningful conversion data; be cautious for short buying cycles, dynamic pages, broad service-list pages, low budgets, or weak conversion signals.+ - Do not assume exact always beats broad: if broad match plus smart bidding converts better because it can use unseen user-journey signals, keep broad and use exact selectively.++6. **Budget increases need opportunity proof**+ - If lost IS due to budget is near 0%, more budget is unlikely to add meaningful traffic.+ - If budget is capped, forecast incremental spend/conversions using lost IS, recent CPA/ROAS, and marginal query quality. New budget can be absorbed by worse broad-match inventory, search partners, cannibalization, or operational bottlenecks.+ - Increasing budget without negative/search-term controls can scale waste.++7. **Rank loss has four common levers**+ - Quality Score/ad relevance/landing page changes.+ - Bid or target changes, including forgotten bid adjustments after strategy changes.+ - Targeting/match-type expansion changing auction mix.+ - Asset coverage and expected impact.++8. **Diagnose conversions as traffic × conversion rate**+ - Conversion change comes from click volume change, conversion-rate change, or both.+ - Isolate by campaign/ad group/device/network/search term/landing page/date, compare year-over-year seasonality, and overlay recent account changes.++9. **RSA tests should measure the advertiser’s goal**+ - Google may serve RSA assets/combinations based heavily on CTR; the advertiser may care about CVR, CPA, ROAS, conversion per impression, revenue per impression, or profit per impression.+ - Use experiments or structured before/after with enough minimum data. Pause losing RSAs only after the chosen metric has sufficient volume and confounders are checked.++10. **RSA structure matters more than asset volume alone**+ - A broad ad group with many intents can cause Google to mismatch assets to queries. Split ad groups when query intent requires specific copy or landing pages.+ - Ad strength is a diagnostic of Google’s asset diversity expectations, not a final performance objective. Pinning can reduce ad strength but may improve message control.++11. **Quality Score work should be componentized**+ - Expected CTR: compare SERP/message attractiveness and query fit.+ - Ad relevance: ensure query themes appear in ad assets without forcing irrelevant repetition.+ - Landing-page experience: match query/ad promise, improve trust, transparency, navigation, speed, mobile UX, and conversion clarity.+ - Trend patterns matter: cliffs often indicate broken pages/disapprovals/tracking/offer changes; slow declines suggest relevance drift or competitor movement.++12. **Search Partner traffic is a separate diagnostic segment**+ - Compare Google Search vs Search Partners for cost, clicks, conversions, CPA/ROAS, conversion rate, search terms, and brand/non-brand composition.+ - If partners are materially worse and volume is meaningful, disable Search Partners; if better, keep but monitor because site mix is opaque and can shift.++13. **Conversion tracking is a prerequisite, not a postscript**+ - Audit conversion action status, primary/secondary inclusion, attribution/counting consistency, duplicate tags/actions, imported action ownership, values/currencies, phone/form/offline coverage, and campaign-specific goal consistency.+ - Do this before optimizing bids, budgets, negatives, or ad tests.++14. **Landing page tests can be independent or bundled with ads**+ - If testing message chains (e.g., discount vs free shipping), pair ad+LP variants.+ - If testing which ad and which page independently wins, use a full factorial setup: each ad to each page.+ - Geographic/service specificity may improve CTR only, CVR only, or both; measure both.++15. **PMax can obscure Search diagnostics**+ - When PMax serves on overlapping queries, Search impression share and search-term opportunity can look different because eligibility/auction priority shifts.+ - Audit overlap between PMax search terms, Search keywords, and Search search terms; compare CTR/CVR/value and use negatives/keyword coverage/routing where controls exist.++## 3) Recommended NotFair skill modules++### Module A — `search-term-ngram-triage`+- **Primary skill home:** `google-ads/manage`; secondary audit integration.+- **Triggers:** “wasted spend,” “search terms,” “add negatives,” “query analysis,” “low conversions,” broad match cleanup, PMax/Search overlap review.+- **Workflow:**+ 1. Pull search terms for 30–90 days by campaign/ad group/network; include cost, clicks, conversions, conversion value, keyword/ad group, and campaign type.+ 2. Tokenize terms into 1-, 2-, and 3-grams; aggregate performance and count distinct queries/campaigns/ad groups.+ 3. Generate action buckets: negative candidates, keyword/add-to-exact candidates, route-to-better-ad-group candidates, ad/LP mismatch candidates, product/content opportunity candidates.+ 4. Apply safeguards: minimum cost/clicks, ignore brand/protected terms unless user confirms, check existing negatives and conflicts, surface examples for each n-gram.+ 5. Recommend or execute bulk negatives/keywords only after user approval and experiment-impact checks.+- **Decision rules:** no-conversion high-spend n-grams are review candidates; high-conversion terms missing as keywords are keyword candidates; same query in multiple ad groups with divergent CVR/CPA is routing candidate.+- **Sources:** n-gram posts; search query decisions; negative steering; PMax/Search overlap.++### Module B — `negative-keyword-hygiene`+- **Primary skill home:** `google-ads/manage` and `google-ads/audit`.+- **Triggers:** “negative keyword audit,” “conflicts,” “shared negative list,” “irrelevant searches,” “B2B consumer traffic,” “duplicates.”+- **Workflow:**+ 1. Inventory campaign/ad-group negatives and shared lists.+ 2. Detect inconsistent campaign coverage for common disqualifiers.+ 3. Detect positive-keyword/search-term conflicts.+ 4. Detect malformed negatives and missing singular/plural/close variants.+ 5. Recommend shared-list consolidation by scope: account-wide, brand/non-brand, product line, geography/routing.+ 6. Produce a safe mutation plan: create/link list, add terms, remove conflicts, or move ad-group negatives to list.+- **Decision rules:** use shared lists for universal exclusions; use ad-group negatives for routing; never remove a conflict without confirming the blocked positive/search term is desirable.+- **Sources:** negative primer; common negative problems; steering the machine; n-gram posts.++### Module C — `broad-match-readiness-and-containment`+- **Primary skill home:** `google-ads/manage`.+- **Triggers:** “should I use broad match,” “Google recommends broad,” “pause exact,” “broad match wasted spend,” “scale campaign.”+- **Workflow:**+ 1. Confirm conversion tracking health and bid strategy.+ 2. Check conversion volume, budget headroom, lost IS, search-term quality, negative coverage, landing-page focus, sales-cycle length, and current exact/phrase winners.+ 3. Classify readiness: safe to test, test with guardrails, or do not expand yet.+ 4. If testing, create a controlled experiment or limited ad-group rollout; pre-build negatives and monitoring thresholds.+ 5. After rollout, compare query mix, CPA/ROAS, CTR, CVR, and incremental conversions; decide whether to keep broad, add exact, or pause exact if broad is better.+- **Decision rules:** broad is riskier with short buying cycles, weak tracking, unfocused/dynamic pages, low budget, and insufficient negatives. Exact is not automatically superior when broad uses valuable journey signals.+- **Sources:** broad-match readiness; when to pause exact; broad match vs CTR/QS; budget scaling article.++### Module D — `rsa-ad-testing-lab`+- **Primary skill home:** `google-ads/copy` and `google-ads/manage`.+- **Triggers:** “test RSAs,” “ad copy underperforming,” “low CTR/CVR,” “ad strength,” “pinning,” “ad group organization.”+- **Workflow:**+ 1. Pull RSA assets, asset performance labels if available, ad-level metrics, ad-group query themes, and landing pages.+ 2. Identify broad/mixed-intent ad groups where assets cannot match every query theme.+ 3. Choose test metric based on business goal: CTR, CVR, CPA, ROAS, conversion per impression, revenue/profit per impression.+ 4. Recommend test type: unpinned RSA optimization, pinned message test, theme-vs-theme test, RSA-vs-existing baseline, or ad+LP message-chain test.+ 5. Use experiments when possible; otherwise require minimum data and note confounders.+ 6. Generate complete RSA replacement assets when mutating; do not rely on ad strength as the winner criterion.+- **Decision rules:** pin when legal/brand/query-message control matters; split ad groups when one RSA contains assets for distinct intents; treat high ad strength as coverage signal, not proof of profitability.+- **Sources:** RSA testing; RSA organization; effective RSAs; ad strength; ad/LP testing.++### Module E — `quality-score-component-diagnosis`+- **Primary skill home:** `google-ads/manage`; landing submodule for LPX.+- **Triggers:** “quality score,” “expected CTR,” “ad relevance,” “landing page experience,” “CPC rose,” “rank lost IS.”+- **Workflow:**+ 1. Pull keyword QS components and performance; segment by campaign/ad group/match type.+ 2. Bucket issues by component: expected CTR, ad relevance, LP experience.+ 3. Overlay recent changes: ads, landing page URL, budgets, bids, targeting, broad-match additions, disapprovals.+ 4. For expected CTR/ad relevance: recommend ad group split, RSA copy, keyword-to-ad theme alignment.+ 5. For LPX: invoke landing-page checklist (message match, trust, transparency, navigation, mobile/speed, conversion clarity).+ 6. Show expected impact as rank/CPA opportunity, not guaranteed QS increase.+- **Decision rules:** do not optimize visible QS in isolation; prioritize high-spend/high-impression keywords with below-average components and material rank/cost impact.+- **Sources:** QS primer/trends; visible vs auction QS; ad relevance; landing-page experience; rank IS diagnostics.++### Module F — `budget-impression-share-triage`+- **Primary skill home:** `google-ads/manage` and `google-ads/audit`.+- **Triggers:** “raise budget,” “limited by budget,” “lost impression share,” “more conversions,” “rank loss,” “top IS changed,” “budget pacing.”+- **Workflow:**+ 1. Pull campaign metrics, budgets, spend, lost IS budget, lost IS rank, search/top/absolute top IS, CPA/ROAS, search terms, and recent changes.+ 2. Classify blocker: no headroom, budget-constrained, rank-constrained, demand/seasonality shift, targeting/match expansion, quality issue, asset issue, PMax overlap.+ 3. For budget-constrained campaigns, estimate incremental spend/conversions from lost IS and marginal CPA/ROAS; flag if current extra traffic is low quality.+ 4. For rank-constrained campaigns, check QS components, bids/targets, bid adjustments, assets, and target changes.+ 5. Recommend budget increases only for campaigns with headroom and acceptable marginal economics; otherwise reallocate from waste.+- **Decision rules:** lost IS budget near zero -> budget increase unlikely; budget increase with broad match/search partners can degrade marginal efficiency; PMax overlap can make Search IS incomplete.+- **Sources:** impression share analysis; lost IS budget; lost IS rank/top IS; budget changes; more budget same results; PMax IS impact.++### Module G — `conversion-tracking-integrity-audit`+- **Primary skill home:** `google-ads/audit`; prerequisite gate for manage actions.+- **Triggers:** first-time audit, “tracking,” “conversions look wrong,” “smart bidding,” “CPA/ROAS unreliable,” “offline conversions.”+- **Workflow:**+ 1. Inventory conversion actions: type, status, category, primary flag, owner, counting type, attribution, value/currency, ECFL/offline/call coverage where available.+ 2. Compare campaign goal settings and included actions for consistency.+ 3. Flag duplicate actions, missing primary actions, irrelevant primary actions, inconsistent counting/attribution, imported/read-only actions, missing values/currencies, and suspicious zero/huge conversion patterns.+ 4. Before bid/budget optimization, summarize whether data is trustworthy enough for automated bidding.+- **Decision rules:** if tracking is materially inconsistent, do not make aggressive bid/budget recommendations; fix measurement first.+- **Sources:** conversion tracking mistakes; assisted conversions; audit checklist.++### Module H — `network-partner-evaluator`+- **Primary skill home:** `google-ads/manage` and `google-ads/audit`.+- **Triggers:** “search partners,” “network performance,” “bad traffic,” “CPA spike,” “conversion rate changed.”+- **Workflow:**+ 1. Segment campaigns by ad network type for Google Search vs Search Partners.+ 2. Compare cost, clicks, CTR, CVR, CPA/ROAS, conversion value, and search-term quality.+ 3. Identify campaigns where partners are material volume and materially worse/better.+ 4. Recommend disabling partners, keeping them, or monitoring with alerts.+- **Decision rules:** disable only when partner traffic is meaningful and worse on the account’s goal metric; avoid conclusions from tiny volume.+- **Sources:** Search Partners evaluation; conversion-change diagnosis; audit checklist.++### Module I — `landing-page-message-match`+- **Primary skill home:** `google-ads/landing`; connected to copy/manage experiments.+- **Triggers:** “landing page experience,” “LPX below average,” “conversion rate dropped,” “test landing pages,” “message match.”+- **Workflow:**+ 1. Map keyword/search-term themes -> RSA claims -> final URLs.+ 2. Score message match, offer consistency, trust/transparency, navigation, page speed/mobile usability, and conversion-action clarity.+ 3. Decide test design: ad-only, LP-only, paired message-chain, or full factorial ad×LP.+ 4. Recommend page variants and experiment setup; track CTR and CVR separately.+- **Decision rules:** if CTR improves but CVR does not, landing page may not reinforce the ad promise; if CVR improves only for local pages, scale by geography/service carefully.+- **Sources:** landing-page experience; 10 LP steps; ad+LP testing posts.++### Module J — `automated-audit-orchestrator`+- **Primary skill home:** `google-ads/audit`.+- **Triggers:** “audit account,” “health check,” “what’s broken,” “quick wins,” recurring monitoring.+- **Workflow:**+ 1. Run deterministic checks first: disapprovals, broken/final URLs, paused/limited entities, missing assets, missing conversion actions, negative conflicts, budget/rank lost IS, search-term waste, zero-conversion spend, landing-page issues, PMax overlap.+ 2. Group findings by financial impact and actionability.+ 3. Separate safe automated fixes from recommendations requiring business judgment.+ 4. Produce a prioritized action plan with source metric, evidence, suggested mutation, risk, and expected direction.+- **Decision rules:** audits should translate findings into likely spend/revenue impact; automate repeatable scans but keep human confirmation for brand, legal, and strategic exclusions.+- **Sources:** ultimate audit checklist; audit automation; asset audit; conversion tracking; all diagnostic modules above.diff --git a/google-ads/shared/saas-b2b-playbook.md b/google-ads/shared/saas-b2b-playbook.mdnew file mode 100644index 00000000..60dc64bd--- /dev/null+++ b/google-ads/shared/saas-b2b-playbook.md@@ -0,0 +1,60 @@+# SaaS / B2B Product-Led Playbook++Use this archetype for SaaS, developer tools, MCP/tools, and product-led B2B acquisition accounts.++## Core posture++Cheap clicks are not success. Optimize toward activation and qualified product intent.++## Conversion hierarchy++Prefer primary conversions close to product value:++1. Paid purchase / qualified opportunity / connected account.+2. First successful product action or diagnosis.+3. First write/request/approval event when that indicates activation.+4. Signup/trial start only if activation is not yet available.+5. Button clicks/page views as secondary diagnostics only.++Do not switch to conversion-based bidding until tracking is reliable and there is enough signal.++## Query intent++High-quality:++- product category + exact workflow+- named integration + problem+- competitor/integration alternatives with clear landing pages+- bottom-funnel problem terms++Risky:++- generic AI/marketing/productivity curiosity+- "free no signup"+- tutorials/courses/definitions+- directories/marketplaces/lists when the product is not a directory+- terms implying affiliation with a platform when the brand relationship is unclear++## Brand trust and Limited Ad Serving++For new advertisers or tool/integration products:++- Make the advertiser brand explicit in headline 1 or above the fold.+- State the relationship clearly: independent tool/integration, not affiliated with platform owners.+- Mirror query intent on landing pages without implying ownership of third-party brands.+- Add trust elements: company identity, privacy/terms/contact, OAuth/data-access explanation, approval boundaries.+- Do not scale spend while Limited Ad Serving, weak QS, or zero activation signal remains unresolved.++## Budget posture++- Use Maximize Clicks only as a short discovery phase with search-term cleanup.+- Move toward Maximize Conversions when activation tracking is reliable.+- Add Target CPA only after observed activation/CAC economics are stable.+- Raise budget only after query quality and activation signal are proven.++## Anti-patterns++- Treating signup volume as quality when activation is absent.+- Buying broad generic AI/software terms before exact problem-aware terms are covered.+- Referencing third-party platforms in a way that creates unclear brand relationship risk.+- Scaling spend because CPC is low.