Skip to content

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.json
index 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.json
index 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.md
index 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
### Changed
diff --git a/VERSION b/VERSION
index 35aa2f3c..16c6b58f 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.25.4
+0.25.5
diff --git a/google-ads/audit/SKILL.md b/google-ads/audit/SKILL.md
index 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 ar
6. **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.md
new file mode 100644
index 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.md
index 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 than
Each 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.md
new file mode 100644
index 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.md
index 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. A
Only 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 pages
diff --git a/google-ads/landing/references/message-chain-testing.md b/google-ads/landing/references/message-chain-testing.md
new file mode 100644
index 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.md
index 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.json
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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 Analysis
1. 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-gram
4. Sort by cost descending to find the most expensive patterns
+5. Classify each pattern into an action bucket before recommending a mutation
+
+### Generalized Action Buckets
+
+| Bucket | Signal | Action |
+|--------|--------|--------|
+| Negative candidate | Irrelevant intent, wrong geography, job seeker, DIY/info, free/cheap when not offered, unwanted competitor/name-seeking | Add negative after checking positive/search-term conflicts |
+| Keyword candidate | Converting query/n-gram not present as a positive keyword | Add as exact or phrase in the most relevant ad group |
+| Routing candidate | Same query/n-gram served by multiple ad groups with divergent CPA/CVR | Add keyword to the best-fit ad group and negative-route from the wrong group |
+| Ad/LP mismatch | Relevant query, poor performance, weak ad relevance or LPX | Rewrite RSA, split ad group, or improve landing page message match |
+| Product/content opportunity | Repeated relevant demand not currently targeted or sold | Flag opportunity; do not negative unless business confirms it is unwanted |
+
+High-spend/no-conversion n-grams are review triggers, not automatic negatives. Always inspect examples.
### Common High-Waste N-grams (Cross-Industry)
diff --git a/google-ads/manage/references/search-term-triage.md b/google-ads/manage/references/search-term-triage.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.