Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

refactor(ads-audit): restructure audit around 5 analysis layers and 3 actionable passes (#36)

Tong Chenfa9c4541ab88
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a39d0dcb..44ea8e36 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,18 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
---
+## [0.11.1] — 2026-04-11
+
+### Changed
+- **Ads audit restructured around 5 analysis layers and 3 actionable passes** — Replaced the 7-dimension scoring model (0-5 per dimension, 0-100 composite) with a layered analysis approach: Signals → Relevance → Efficiency → Scale → Growth. Findings now map to 3 action-oriented passes: Stop Wasting, Capture More, Fix Fundamentals. Tracks 3 objective pulse metrics (waste rate, demand captured, CPA) with trend comparison on re-audits
+- **Added PMax campaign support** — Asset group completeness checks, PMax cannibalization detection for brand Search traffic, and PMax-specific bid strategy guidance
+- **Added audience signals check** — Flags Search campaigns missing audience segments and PMax asset groups without audience signals, both of which limit Smart Bidding performance
+- **Smarter waste calculation** — Keyword waste threshold changed from "clicks > 10" to "spend > 2x account average CPA", which respects Smart Bidding's learning curve. Added de-duplication rules to prevent double-counting between keyword and search term waste
+- **On-demand reference loading** — Quality score, search term analysis, industry benchmarks, and campaign structure references now load only when relevant issues are detected, saving ~1,000 lines of context per audit
+- **Extracted reference docs** — Persona discovery template and business context crawl procedure moved to dedicated reference files for reuse across skills
+
+---
+
## [0.11.0] — 2026-04-09
### Added
diff --git a/VERSION b/VERSION
index d9df1bbc..af88ba82 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.11.0
+0.11.1
diff --git a/google-ads/ads-audit/SKILL.md b/google-ads/ads-audit/SKILL.md
index 1a08e0bb..87b05377 100644
--- a/google-ads/ads-audit/SKILL.md
+++ b/google-ads/ads-audit/SKILL.md
@@ -25,17 +25,17 @@ The user may pass arguments that narrow the audit to specific campaigns, service
| User says | Scope | Behavior |
|-----------|-------|----------|
-| No arguments / "audit my ads" | **Full account** | Audit all campaigns, all dimensions |
-| "focus on grooming" / "grooming campaigns" | **Service-scoped** | Filter to campaigns matching the service keyword. Still pull account-level data for context (conversion tracking, account settings), but deep-dive analysis, scoring, and recommendations focus on the matched campaigns only |
+| No arguments / "audit my ads" | **Full account** | Audit all campaigns, all passes |
+| "focus on grooming" / "grooming campaigns" | **Service-scoped** | Filter to campaigns matching the service keyword. Still pull account-level data for context (conversion tracking, account settings), but deep-dive analysis and recommendations focus on the matched campaigns only |
| "campaign X" / specific campaign name | **Campaign-scoped** | Same as service-scoped but matched to exact campaign(s) |
-| "just check wasted spend" / "impression share" | **Dimension-scoped** | Full data pull but report only the requested dimension(s) in depth. Scorecard still shows all 7 dimensions for context, but detailed findings and actions focus on the requested area |
+| "just check wasted spend" / "impression share" | **Focus-scoped** | Full data pull but report only the requested area in depth. All 3 passes still run for context, but detailed findings and actions focus on the requested area |
### Scope threading rules
1. **Always pull `listCampaigns` unfiltered first** — you need the full picture to identify which campaigns match the scope and to calculate account-wide metrics like total spend (needed for waste percentages)
2. **Filter deep-dive data to scoped campaigns** — In Phase 1B, only pull per-campaign data (`getCampaignSettings`, `getKeywords`, `getSearchTermReport`, `listAds`) for campaigns matching the scope. This saves API calls and keeps the analysis focused
-3. **Score dimensions relative to scope** — If scoped to grooming campaigns, keyword health score reflects grooming keywords only, not the whole account. Make this explicit in the report header: "Scoped to: [Grooming campaigns]"
-4. **Account-wide dimensions still get scored** — Conversion tracking and account settings are account-level regardless of scope. Score them normally but note when issues affect the scoped campaigns specifically
+3. **Analyze relative to scope** — If scoped to grooming campaigns, waste calculations and keyword analysis reflect grooming keywords only, not the whole account. Make this explicit in the report header: "Scoped to: [Grooming campaigns]"
+4. **Account-wide checks still run** — Signal quality, tracking, and account settings are account-level regardless of scope. Check them normally but note when issues affect the scoped campaigns specifically
5. **Persona discovery uses scoped data** — Build personas from search terms within the scoped campaigns only
6. **Business context is always full-account** — `business-context.json` captures the whole business, not just the scoped segment. Don't narrow business context to the scope
@@ -45,19 +45,22 @@ Match campaign names, ad group names, and keyword themes using case-insensitive
## Reference Documents
-Read these reference documents during analysis for expert-level context:
+**Always read before Phase 2:**
+- `references/account-health-scoring.md` — Diagnostic thresholds, red flags, interpretation matrices, and benchmark tables
-- `references/account-health-scoring.md` — Detailed scoring rubrics for each dimension (0-5 scale with specific criteria)
-- Read from ads skill: `../ads/references/industry-benchmarks.md` — Compare account metrics to industry averages
-- Read from ads skill: `../ads/references/quality-score-framework.md` — QS diagnostics and component-level analysis
-- Read from ads skill: `../ads/references/search-term-analysis-guide.md` — Search term relevance scoring methodology
-- Read from ads skill: `../ads/references/campaign-structure-guide.md` — Account structure best practices
+**Read during Phase 2.5 / Phase 3:**
+- `references/persona-discovery.md` — Persona template, derivation rules, and JSON schema (read during Phase 2.5)
+- `references/business-context.md` — Website crawl procedure and business-context.json schema (read during Phase 3)
-Read these before starting Phase 2 analysis. They contain the numeric thresholds that separate a generic audit from an expert one.
+**Read on demand** — only load these when the analysis surfaces a relevant issue. Loading all of them upfront wastes ~1,000 lines of context:
+- `../ads/references/quality-score-framework.md` — Read only if avg QS < 6 or high-spend keywords have QS < 5
+- `../ads/references/search-term-analysis-guide.md` — Read only during Layer 2 search term quality analysis
+- `../ads/references/industry-benchmarks.md` — Read only during Layer 3 efficiency analysis for CPA comparison
+- `../ads/references/campaign-structure-guide.md` — Read only if structural issues detected (>30 keywords per ad group, brand/non-brand mixed, poor naming)
-## Step 0: Policy Freshness Check
+## Step 0: Policy Freshness Check (runs in parallel with Phase 1A)
-Before auditing, verify that the policy assumptions underpinning this audit are current.
+Verify policy assumptions are current — but don't block data collection on it. Run this check in parallel with Phase 1A since they're independent.
1. Read `../shared/policy-registry.json` and check each entry: if `last_verified` + `stale_after_days` < today's date, the entry is stale.
2. **High-volatility stale entries:** Use WebSearch to check for recent Google Ads changes related to each stale entry's `area` (e.g., "Google Ads broad match behavior changes 2026"). Compare findings against the `assumption` field. If discrepancies are found:
@@ -66,12 +69,12 @@ Before auditing, verify that the policy assumptions underpinning this audit are
3. **Moderate-volatility stale entries:** Note them in the audit output as an informational line (e.g., "ℹ️ [area] last verified [date] — may warrant a check") but do not block the audit.
4. **Stable stale entries:** Skip — these rarely change.
-If no high-volatility entries are stale, proceed directly to Phase 1 with no output from this step.
-
## Phase 1: Pull Account Data
Gather everything in parallel before asking the user a single question. The goal is to show up informed.
+**Date range:** Default to `LAST_30_DAYS` for a full audit — 30 days gives enough signal for meaningful waste calculations, impression share trends, and bid strategy assessment. Use `LAST_7_DAYS` only for daily campaign performance queries on accounts with 3+ campaigns (to stay within GAQL's 50-row limit).
+
**Use the adaptive data fetching algorithm from `../shared/gaql-cookbook.md`.** The approach varies by account size — read the cookbook's "Adaptive data fetching algorithm" section. Here's the summary:
### Phase 1A: Account basics + sizing probe (parallel)
@@ -86,15 +89,49 @@ Pull these simultaneously — they don't require campaign IDs and they tell you
**After Phase 1A, apply scope filtering:** If the user specified a scope (see Scope Detection above), identify which campaigns match. Log the matched campaigns and their IDs. If no campaigns match, stop and ask the user to clarify. For the rest of the audit, "active campaigns" means scope-matched campaigns (or all campaigns if no scope was specified).
-**Also after Phase 1A: kick off the website crawl.** Once `listAds` data is available, resolve the website URL and start the website crawl (Phase 3, Step 2) immediately — don't wait for Phase 1B or Phase 2. The crawl results aren't needed until Phase 3's user questions, so it runs in the background while you finish data collection and scoring.
+**After Phase 1B: kick off the website crawl.** Once `listAds` data is available (pulled in Phase 1B), resolve the website URL and start the website crawl (see `references/business-context.md`) immediately. The crawl results aren't needed until Phase 3's user questions, so it runs in the background while you finish analysis.
### Phase 1B: Adaptive data pull (depends on account size)
-Count the **in-scope** enabled campaigns with spend from Phase 1A, then follow the cookbook. When scoped, only pull per-campaign data for in-scope campaigns — but still run account-wide GAQL queries (they're cheap and provide context for scoring):
+Count the **in-scope** enabled campaigns with spend from Phase 1A, then follow the cookbook's adaptive algorithm. When scoped, only pull per-campaign data for in-scope campaigns — but still run account-wide GAQL queries (they're cheap and provide context).
+
+**In addition to the cookbook's strategy**, always pull `getCampaignSettings(campaignId)` and `listAds(campaignId)` for each in-scope campaign (needed for Display Network detection, bidding strategy assessment, and ad copy analysis).
+
+### PMax data pull
+
+For each in-scope PMax campaign (identified from `listCampaigns` by campaign type), pull in parallel:
+- `getPmaxAssetGroups(campaignId)` — asset group status and performance
+- `getPmaxAssets(assetGroupId)` for each asset group — completeness check (headlines, images, video)
+
+### Audience segment pull
+
+Pull audience data for Search campaigns via GAQL — needed for the Layer 2 audience signals check. PMax audience signals come from `getPmaxAssetGroups` (already pulled above).
+
+Search campaign audiences are typically set at the **ad group level** (observation mode), not at campaign level. Query both levels — finding audiences at either level means the check passes:
+
+```
+SELECT campaign.id, campaign.name,
+ ad_group.id, ad_group.name,
+ ad_group_criterion.type,
+ ad_group_criterion.user_list.user_list
+FROM ad_group_criterion
+WHERE campaign.id IN (<in-scope campaign IDs>)
+ AND ad_group_criterion.type IN ('USER_LIST', 'CUSTOM_AUDIENCE', 'COMBINED_AUDIENCE')
+ AND campaign.status = 'ENABLED'
+```
+
+If this returns zero rows, also check campaign-level criteria (less common but possible):
+
+```
+SELECT campaign.id, campaign.name,
+ campaign_criterion.type,
+ campaign_criterion.user_list.user_list
+FROM campaign_criterion
+WHERE campaign.id IN (<in-scope campaign IDs>)
+ AND campaign_criterion.type IN ('USER_LIST', 'CUSTOM_AUDIENCE', 'COMBINED_AUDIENCE')
+```
-- **1-3 in-scope campaigns:** Run all 7 standard GAQL queries in parallel. Also run `getCampaignSettings(campaignId)` and `listAds(campaignId)` per in-scope campaign (needed for Display Network detection, bidding strategy assessment, and ad copy scoring). Done.
-- **4-10 in-scope campaigns:** Run all 7 GAQL queries + `getCampaignSettings` and `listAds` for top 3-5 in-scope campaigns by spend. If keywords or search terms hit the 50-row limit, supplement with `getKeywords`/`getSearchTermReport` for the top 2-3 in-scope campaigns.
-- **10+ in-scope campaigns:** Use the tiered approach — GAQL for account-wide overview (impression share, ad groups, negatives, daily performance), then per-campaign helpers (`getCampaignSettings`, `getKeywords`, `getSearchTermReport`, `listAds`) for the top in-scope campaigns that cover 80% of in-scope spend.
+If both queries return zero rows for all Search campaigns, flag "no audience segments" in Layer 2.
### Geo-targeting verification
@@ -111,7 +148,7 @@ WHERE campaign.id IN (<in-scope campaign IDs>)
AND campaign_criterion.type IN ('LOCATION', 'PROXIMITY')
```
-`radius_units` values: 0 = meters, 1 = kilometers, 2 = miles. Do NOT claim "no geo-targeting" based solely on `getCampaignSettings` — the GAQL query is authoritative.
+`radius_units` enum: `UNSPECIFIED` = 0, `UNKNOWN` = 1, `MILES` = 2, `KILOMETERS` = 3. There is no "meters" value — Google Ads only supports miles and kilometers for proximity targeting. Do NOT claim "no geo-targeting" based solely on `getCampaignSettings` — the GAQL query is authoritative.
### Fallback
@@ -119,230 +156,213 @@ If `runGaqlQuery` errors or is unavailable, fall back to per-campaign helper too
**Minimum data for a meaningful audit:** Campaign list, keyword data, impression share, and conversion actions must return data. If the account has zero campaigns or zero spend, skip to Phase 3 (business context).
-## Phase 2: Analyze and Score
-
-Work through each dimension. For each one, assign a numeric score (0-5) and a status label.
-
-**Scope-aware scoring:** When the audit is scoped, score campaign-level dimensions (structure, keyword health, search terms, ad copy, impression share, spend efficiency) using only in-scope data. Account-level dimensions (conversion tracking) are scored account-wide but with notes about how issues affect the scoped campaigns. The overall health score reflects scoped performance — this gives the user a focused view of the area they care about.
-
-### Scoring Framework
-
-Read `references/account-health-scoring.md` for the detailed rubric per dimension. Use this summary for quick reference:
-
-**Score definitions:**
-
-| Score | Label | Meaning |
-|-------|-------|---------|
-| 0 | Critical | Broken or missing entirely — actively losing money |
-| 1 | Poor | Major problems — significant waste or missed opportunity |
-| 2 | Needs Work | Below acceptable — several clear issues to fix |
-| 3 | Acceptable | Functional but room for meaningful improvement |
-| 4 | Good | Well-managed with minor optimization opportunities |
-| 5 | Excellent | Best-practice level — maintain and scale |
-
-**Overall Health Score:** Sum all 7 dimension scores, multiply by (100/35), round to nearest integer. This gives a 0-100 score.
-
-| Overall Score | Label | Summary |
-|---------------|-------|---------|
-| 0-25 | Critical | Account has fundamental problems. Stop spending until fixed |
-| 26-50 | Needs Work | Significant waste. Focus on top 3 issues before scaling |
-| 51-75 | OK | Functional but leaving money on the table |
-| 76-90 | Strong | Well-managed. Focus on scaling and marginal gains |
-| 91-100 | Excellent | Top-tier account. Maintain and test incrementally |
-
-### Account Health Dimensions
-
-**1. Conversion tracking** (Score 0-5)
-
-| Score | Criteria |
-|-------|----------|
-| 0 | No conversion actions set up. Spending blind |
-| 1 | Conversion actions exist but aren't firing (0 conversions recorded despite clicks) |
-| 2 | Conversions tracked but auto-tagging disabled, or using only micro-conversions (page views, not leads/sales) |
-| 3 | Primary conversion action firing, auto-tagging on, but multiple conversion actions counting duplicates or no value assigned |
-| 4 | Clean conversion setup: primary action firing, auto-tagging on, values assigned, no duplicate counting |
-| 5 | Full setup: primary + secondary actions, proper attribution window, enhanced conversions or offline conversion import |
-
-- Red flag: spending money with no conversion tracking = flying blind. Score 0-1 is a STOP condition — recommend pausing spend until tracking is fixed
-- Check: is auto-tagging enabled? If not, Google Analytics integration breaks
-- Check: are conversion actions using "Every" or "One" counting? Lead gen should use "One", e-commerce should use "Every"
-
-**2. Campaign structure** (Score 0-5)
-
-| Score | Criteria |
-|-------|----------|
-| 0 | Single campaign with one ad group containing 50+ unrelated keywords |
-| 1 | Some structure but ad groups have 30+ keywords with mixed intent (e.g., "plumber" and "plumbing school" in same group) |
-| 2 | Campaigns exist per service/product but ad groups are too broad (15-30 keywords of mixed theme) |
-| 3 | Campaigns per service, ad groups by theme (5-20 keywords), but missing brand campaign separation or geo structure |
-| 4 | Clean structure: brand separated, services split, tight ad groups, appropriate geo targeting |
-| 5 | Optimal: brand/non-brand split, service campaigns, geo-specific where relevant, ad groups of 5-15 tightly themed keywords, negative keyword lists at appropriate levels |
-
-- Red flag: one ad group with 200 keywords = poor relevance, QS will suffer
-- Check: are brand and non-brand keywords in separate campaigns? Mixing them inflates brand CTR and hides non-brand problems
-- Check: for multi-location businesses, is there geo-specific structure?
-- Reference `../ads/references/campaign-structure-guide.md` for the ideal structure patterns
-
-**3. Keyword health** (Score 0-5)
-
-| Score | Criteria |
-|-------|----------|
-| 0 | No keywords with conversions. Average QS < 3. >50% of keywords are zombies (0 impressions 30+ days) |
-| 1 | Average QS 3-4. >30% of spend on non-converting keywords. Heavy use of broad match without negatives |
-| 2 | Average QS 4-5. 20-30% of spend on non-converting keywords. Some match type issues |
-| 3 | Average QS 5-6. 10-20% wasted spend. Reasonable match type mix but gaps in negative coverage |
-| 4 | Average QS 6-7. <10% wasted spend. Good match type strategy. Solid negative keyword lists |
-| 5 | Average QS 7+. <5% wasted spend. Tight match types. Comprehensive negatives. Regular search term mining |
-
-- Calculate: what % of total keyword spend goes to keywords with 0 conversions and >10 clicks? This is your keyword waste rate
-- Calculate: average QS weighted by spend (not by keyword count — a QS-3 keyword spending $2,000/month matters more than a QS-3 keyword spending $5/month)
-- Check for zombie keywords: 0 impressions for 30+ days. These clutter the account and should be paused
-
-**4. Search term quality** (Score 0-5)
-
-| Score | Criteria |
-|-------|----------|
-| 0 | >40% of search terms are irrelevant. No negative keywords in place |
-| 1 | 30-40% irrelevant terms. Minimal negative keyword coverage |
-| 2 | 20-30% irrelevant terms. Some negatives but obvious gaps |
-| 3 | 10-20% irrelevant terms. Decent negative coverage. Some converting terms not yet added as keywords |
-| 4 | <10% irrelevant terms. Good negative lists. Most high-converting terms already added as keywords |
-| 5 | <5% irrelevant terms. Comprehensive negative lists at account and campaign level. Active search term mining program |
-
-- Score search term relevance using the methodology in `../ads/references/search-term-analysis-guide.md`
-- Calculate: spend on irrelevant search terms (relevance score < 2) as % of total spend
-- Flag converting search terms (2+ conversions) not yet added as keywords — these are free money
-- Flag obvious negative keyword gaps: competitor names, "free" variants, "jobs"/"careers" variants, wrong service types
-
-**5. Ad copy** (Score 0-5)
-
-| Score | Criteria |
-|-------|----------|
-| 0 | No active ads, or only legacy expanded text ads (no RSAs) |
-| 1 | RSAs exist but only 1 per ad group. Headline/description variety is poor (repetitive messaging) |
-| 2 | 1-2 RSAs per ad group. Some variety but headlines don't include keywords or location |
-| 3 | 2+ RSAs per major ad group. Headlines include keywords. Pinning used on H1. Some CTR variation suggests testing is happening |
-| 4 | 2-3 RSAs per ad group with distinct messaging angles. Good headline variety (service, value prop, trust, CTA). CTR above industry average |
-| 5 | Active A/B testing program. Multiple RSAs with measurably different angles. Regular losers paused, winners iterated. CTR consistently above benchmark |
-
-- Count RSAs per ad group: <2 means no testing is possible
-- Check headline diversity: are the 15 headlines actually different, or are they minor variations of the same message?
-- Check if keywords appear in headlines (direct QS and relevance impact)
-- Check pin strategy: H1 should typically be pinned to the most relevant service+location headline
-- Identify ad groups with CTR below industry benchmark — these need copy refresh
-
-**6. Impression share** (Score 0-5) — **Data limit:** `getImpressionShare` supports max 90 days (not 365 like other tools). For GAQL impression share queries, the same 90-day practical limit applies.
-
-| Score | Criteria |
-|-------|----------|
-| 0 | Search IS < 20%. Missing >80% of potential traffic |
-| 1 | Search IS 20-35%. Budget-lost IS > 40% OR rank-lost IS > 60% |
-| 2 | Search IS 35-50%. Significant losses from both budget and rank |
-| 3 | Search IS 50-65%. Moderate losses — budget-lost IS < 25% and rank-lost IS < 40% |
-| 4 | Search IS 65-80%. Losses primarily from rank (fixable with QS improvements) |
-| 5 | Search IS > 80%. Brand campaign IS > 95%. Losses are marginal and strategic (intentionally not competing on some queries) |
-
-Use the Impression Share Interpretation Matrix to diagnose the root cause:
-
-| | Rank-Lost IS < 30% | Rank-Lost IS 30-50% | Rank-Lost IS > 50% |
-|---|---|---|---|
-| **Budget-Lost IS < 20%** | Healthy — optimize at margins | QS/Bid Problem — improve ads, landing pages, or raise bids on high-QS keywords | Quality Crisis — QS is the bottleneck. Fix ad relevance and landing page experience before spending more |
-| **Budget-Lost IS 20-40%** | Budget Problem — increase budget or narrow targeting. Check if the campaign is profitable enough to justify more spend | Mixed Problem — fix quality first (cheaper than adding budget), then reassess | Structural Problem — bidding on too-competitive keywords. Shift to long-tail and exact match |
-| **Budget-Lost IS > 40%** | Severe Budget Gap — if CPA is good, this is the highest-ROI fix in the account. Double budget or cut keyword count by 50% | Priority: fix rank issues to get more from existing budget, then add budget | Fundamental Misalignment — pause, restructure, then restart. Current approach is burning money |
-
-**7. Spend efficiency** (Score 0-5)
-
-| Score | Criteria |
-|-------|----------|
-| 0 | No conversion data available. Flying blind on efficiency |
-| 1 | CPA > 200% of industry average. >40% of spend on non-converting entities |
-| 2 | CPA 150-200% of industry avg. 25-40% wasted spend. Major budget misallocation between campaigns |
-| 3 | CPA 100-150% of industry avg. 15-25% wasted spend. Some misallocation |
-| 4 | CPA within industry norms. <15% wasted spend. Budget roughly proportional to conversion share per campaign |
-| 5 | CPA below industry avg. <5% wasted spend. Budget allocation optimized — each campaign's budget share matches its conversion share |
-
-- Calculate: % of spend going to converting keywords vs non-converting
-- Calculate: per-campaign CPA and compare to account average. Flag any campaign with CPA > 150% of account avg
-- Calculate: budget allocation efficiency — does each campaign's % of total budget match its % of total conversions?
-- If one campaign gets 60% of budget but delivers only 30% of conversions, that's a $X reallocation opportunity
-
-### Wasted Spend Deep Dive
-
-Calculate wasted spend using this formula (same as `/ads` skill for consistency):
+**Small/new account gate:** If total spend < $500 or total conversions < 10 in the date range, the account doesn't have enough data for meaningful waste rate, demand captured, or CPA metrics. Run a **simplified audit**:
+1. Layer 1 (tracking check) — still critical, catch setup problems early
+2. Layer 2 (structure check only) — campaign organization, keyword themes, ad copy completeness
+3. Skip Layers 3-5 — they'd be statistically meaningless. Still compute and persist pulse metrics (with a "low data" caveat) so re-audits have a baseline
+4. Report format: use the same 3-pass template but note "Limited data — metrics will be meaningful after 30+ days with $500+ spend." Focus recommendations on structural setup, not optimization
+5. Still run Phase 2.5 (personas) and Phase 3 (business context) — these are valuable regardless of data volume
+
+## Phase 2: Analyze
+
+The audit analyzes the account in **5 layers** (each depends on the one below), then presents findings as **3 actionable passes** (organized by what the user should do). The layers determine analysis order — the passes determine report order.
```
-WASTED SPEND =
- Keyword Waste:
- Sum of spend on keywords where (conversions = 0 AND clicks > 10)
- + Search Term Waste:
- Sum of spend on search terms where relevance_score < 2
- (use the 1-5 relevance scoring from ../ads/references/search-term-analysis-guide.md)
- + Structural Waste:
- Spend on campaigns with Display Network enabled where display clicks > 20 AND display conversions = 0
+Analysis layers (work through in order):
+ Layer 1: Signals → "Can I trust the data?"
+ Layer 2: Relevance → "Am I in the right auctions?"
+ Layer 3: Efficiency → "Am I spending wisely?"
+ Layer 4: Scale → "How do I get more?"
+ Layer 5: Growth → "What's next?"
+
+Report passes (organized by action type):
+ Pass 1: Stop Wasting → findings that represent money being burned
+ Pass 2: Capture More → missed opportunities to get more conversions
+ Pass 3: Fix Fundamentals → structural issues that compound over time
```
-Use these numbers internally for scoring. In the report, mention the total waste figure in the verdict paragraph. Individual wasteful keywords/terms appear as evidence under the relevant dimension (keyword health or search term quality) — max 3 examples per category, not exhaustive lists.
+**Scope-aware analysis:** When the audit is scoped, analyze campaign-level data using only in-scope campaigns. Account-level checks (tracking, settings) run account-wide but note how issues affect the scoped campaigns.
-## Phase 2.5: Persona Discovery
+Read `references/account-health-scoring.md` for diagnostic thresholds, red flags, and interpretation matrices. Use it as a reference for severity — the thresholds tell you what's "bad enough to flag" vs. "acceptable."
-Discover 2-3 customer personas from the ad data. This runs in parallel with Phase 3 (business context questions) — it uses only the data already pulled in Phase 1.
+---
-### Data Sources for Persona Construction
+### Layer 1: Signals — "Can I trust the data?"
-| Source | What it reveals | How to access |
-|--------|----------------|---------------|
-| Search terms | What customers actually search for — their language, pain points, urgency | `getSearchTermReport` from Phase 1 |
-| Converting keywords | What they buy — the terms that lead to conversions reveal purchase intent | `getKeywords` filtered to converting |
-| Ad group themes | How the business segments its services — each theme may serve a different persona | `listAdGroups` from Phase 1 |
-| Landing page URLs | Where they land — different pages suggest different customer journeys | `listAds` final URLs from Phase 1 |
-| Geographic data | Where they are — metro vs rural, specific cities | `getCampaignSettings` location targets |
-| Device split | How they search — mobile-heavy suggests on-the-go/urgent need | Infer from ad performance patterns |
-| Time-of-day patterns | When they search — business hours vs evenings vs weekends | `getCampaignPerformance` daily data |
+If signals are broken, every insight downstream is built on lies — and Smart Bidding can't optimize what it can't measure.
-### Persona Template
+**Hard stop conditions** (→ Pass 1, top priority):
+- Zero conversion actions set up → "Stop spending. Set up conversion tracking first."
+- Conversion actions exist but 0 conversions recorded despite 50+ clicks → "Tracking is broken. Fix it before spending another dollar."
+- Only micro-conversions (page views, button clicks) as primary actions → "You're optimizing for the wrong thing. Set up a real conversion action (form submit, phone call, purchase)."
-Use this full template for the persisted JSON file. In the **report output**, personas appear as a compact 3-column table (name, example searches, value) — see Phase 4. The JSON file has the full detail for downstream skills like `/ads-copy`:
+If any hard stop triggers, skip to Phase 4 with the tracking fix as the only recommendation. No point analyzing what you can't measure.
-| Field | Description | Example |
-|-------|-------------|---------|
-| **Name** | Descriptive label capturing their defining trait | "The Emergency Caller" |
-| **Demographics** | Role, context, location type | Homeowner, suburban, dual-income household |
-| **Primary goal** | What they're trying to accomplish RIGHT NOW | Fix a burst pipe before it damages the floor |
-| **Pain points** | What's driving them to search | Can't wait for regular business hours. Worried about cost. Doesn't know who to trust |
-| **Search language** | Actual search terms from the data that this persona uses | "emergency plumber near me", "plumber open now", "burst pipe repair cost" |
-| **Decision trigger** | What makes them click the ad and convert | Seeing "24/7" and "Same Day" in the headline. Phone number in the ad. Reviews mentioned |
-| **Value to business** | Estimated revenue or conversion value | High urgency = willing to pay premium. Avg ticket $350-800 |
+**Checks** (flag issues, assign to appropriate pass):
+- Auto-tagging: is it enabled? If not, Google Analytics integration breaks (→ Pass 3)
+- Counting method: "Every" vs "One"? Lead gen should use "One", e-commerce should use "Every" (→ Pass 1 if inflating conversion count)
+- **Enhanced Conversions:** Is hashed first-party data being sent? Without it, cross-device and cross-browser journeys are invisible to Smart Bidding (→ Pass 3)
+- **Consent Mode v2:** Mandatory for EU since March 2024. Without it, bid strategies are flying blind in privacy-regulated markets (→ Pass 3)
+- **Data density:** Smart Bidding needs 30+ conversions/month per campaign for tCPA, 50+ for tROAS. If a campaign uses automated bidding but has <15 conversions/month, the algorithm doesn't have enough signal to learn (→ Pass 3)
+- **Attribution model:** Last-click attribution is deprecated — data-driven attribution (DDA) is the only model for new conversion actions. Flag any existing actions still on last-click (→ Pass 3)
-### Derivation Rules
+---
-- Each persona MUST be grounded in actual search term clusters from the data. If you can't point to 5+ search terms that this persona would use, the persona is speculative — drop it
-- If all search terms look the same (single-intent account), identify 1-2 personas max. Don't force 3
-- Name personas by their dominant behavior, not demographics: "The Comparison Shopper" is more useful than "Female 35-44"
-- Include the actual search terms from the data that map to each persona — this directly informs ad copy decisions
+### Layer 2: Relevance — "Am I in the right auctions?"
-### Persist Personas
+Before asking "am I getting enough impressions?", ask "are these the right impressions?" and "am I competitive in the auctions I'm entering?"
-Save to `{data_dir}/personas/{accountId}.json`:
+#### Pre-checks (settings that silently burn money) → Pass 1
-```json
-{
- "account_id": "1234567890",
- "saved_at": "2024-01-15T10:30:00Z",
- "personas": [
- {
- "name": "The Emergency Caller",
- "demographics": "Homeowner, suburban, any age",
- "primary_goal": "Fix an urgent problem right now",
- "pain_points": ["Can't wait", "Worried about cost", "Doesn't know who's reliable"],
- "search_terms": ["emergency plumber near me", "plumber open now", "burst pipe repair"],
- "decision_trigger": "24/7 availability, phone number visible, reviews",
- "value": "High — willing to pay premium for urgency"
- }
- ]
-}
-```
+These are checked first because they affect every dollar spent:
+
+**Location targeting intent:** Check `getCampaignSettings` for each active campaign. The field is `campaign.geo_target_type_setting.positive_geo_target_type`. Verify it's set to **`PRESENCE`** — NOT `PRESENCE_OR_INTEREST` (Google's default, which shows ads to anyone *searching about* your location from anywhere in the world). For a local business, this can waste 20-30% of budget.
+
+**Search Partners:** Check if Search Partners is enabled. If search partner clicks are high but conversions are zero → recommend turning it off.
+
+**Display Network leakage:** Check `networkDisplayEnabled` on Search campaigns. If any Search campaign has Display Network on with display clicks > 20 and 0 display conversions → turn off Display Network.
+
+#### Campaign structure analysis
+
+- Are brand and non-brand keywords in separate campaigns? Mixing them inflates brand CTR and hides non-brand problems (→ Pass 3)
+- For multi-location businesses, is there geo-specific structure? (→ Pass 3)
+- One ad group with 200 keywords = poor relevance, QS will suffer (→ Pass 3)
+- **PMax cannibalization:** If PMax campaigns exist alongside Search campaigns, check whether PMax is eating high-intent brand search traffic. Compare brand Search campaign IS — if it's below 90% with PMax running, PMax may be cannibalizing. Recommend adding brand terms as negative keywords in PMax (→ Pass 1 if significant spend, Pass 3 if structural)
+- Reference `../ads/references/campaign-structure-guide.md`
+
+#### Keyword health analysis
+
+- Calculate keyword waste: spend on keywords where `conversions = 0 AND spend > 2x account average CPA`. The 2x CPA threshold respects Smart Bidding's learning curve — a keyword that's spent double your typical conversion cost with nothing to show has had a fair shot (→ Pass 1)
+- Before killing any keyword with $50+ spend, check assisted conversions. If it has assists, investigate before pausing
+- Average QS weighted by spend (not by keyword count) — a QS-3 keyword spending $2,000/month matters more than a QS-3 keyword spending $5/month (→ Pass 3 if QS < 5 on high-spend keywords)
+- Zombie keywords: 0 impressions for 30+ days → pause (→ Pass 1)
+- Reference `../ads/references/quality-score-framework.md`
+
+#### Search term quality analysis
+
+- Score search term relevance using `../ads/references/search-term-analysis-guide.md`
+- Flag irrelevant search terms by category: wrong service, wrong location, wrong intent, competitor names, brand terms in non-brand campaigns (→ Pass 1)
+- **Negative conflict cross-check:** Before recommending new negatives, cross-reference them against converting keywords and converting search terms. If a proposed negative would block a converting term, don't add it
+- Flag converting search terms (2+ conversions) not yet added as keywords (→ Pass 2)
+- Flag obvious negative keyword gaps: "free" variants, "jobs"/"careers" variants, wrong service types (→ Pass 1)
+
+#### Ad copy & creative health
+
+- RSA count per ad group: <2 means no testing is possible (→ Pass 3)
+- Headline diversity: are the 15 headlines actually different? Check if keywords appear in headlines
+- Ad extensions/assets: sitelinks, callouts, structured snippets, image extensions. Missing assets reduce Ad Rank (→ Pass 3)
+- **PMax asset groups:** For each PMax campaign, check asset group completeness via `getPmaxAssets`:
+ - Headlines: at least 5 (max 15)
+ - Long headlines: at least 1
+ - Descriptions: at least 2
+ - Marketing images: at least 1 landscape + 1 square
+ - Logo: at least 1
+ - Video: at least 1. If missing, Google auto-generates low-quality video — flag it (→ Pass 3)
+
+#### Audience signals check
+
+Google's algorithms lean heavily on audience signals — campaigns without them are competing with less data than competitors.
+
+- **PMax asset groups:** Check if audience signals are configured (custom segments, your data segments, interests). PMax without audience signals forces Google to start cold — it'll spend more during the learning phase finding the right audience (→ Pass 3)
+- **Search campaigns:** Check for audience segments (observation or targeting mode). If no audiences are attached, the account is missing bid signal data that could improve Smart Bidding performance (→ Pass 3)
+- **Remarketing/customer match:** If no remarketing lists or customer match audiences exist in the account, flag as a coverage gap — these are the highest-ROAS audiences available (→ Pass 2)
+
+#### Auction fitness (Lost IS — Rank) → Pass 3
+
+Lost IS (Rank) is a *relevance* signal, not a scale signal. High rank-lost IS means your Ad Rank is insufficient.
+
+- Isolate Lost IS (Rank) from impression share data. If rank-lost IS > 30%, diagnose via QS components:
+ - Expected CTR below average → ad copy needs rewriting
+ - Ad relevance below average → ad group themes too broad
+ - Landing page experience below average → page speed, mobile UX, content mismatch
+- **Do not recommend "spend more" for rank-lost IS.** The fix is improving relevance, not more budget
+
+---
+
+### Layer 3: Efficiency — "Am I spending wisely?"
+
+#### Impression share interpretation
+
+Use the **Impression Share 2x2 Interpretation Matrix** from `references/account-health-scoring.md` to classify each campaign as healthy, relevance problem, capital problem, or structural problem. The matrix determines whether the fix is "improve ads/QS" vs. "increase budget" — getting this wrong gives exactly the wrong advice.
+
+#### Spend efficiency
+
+- Calculate: per-campaign CPA and compare to account average. Flag any campaign with CPA > 150% of account avg (→ Pass 1)
+- Calculate: budget allocation efficiency — does each campaign's % of total budget match its % of total conversions? If one campaign gets 60% of budget but delivers only 30% of conversions, that's a reallocation opportunity (→ Pass 1)
+- **PMax efficiency:** If PMax CPA is dramatically worse than Search CPA (>2x) for the same services, PMax may be spending on low-intent display/video traffic (→ Pass 1)
+
+#### Brand vs. Non-Brand segmentation
+
+Many accounts show great ROAS, but 80% comes from brand traffic — paying Google a tax on existing customers.
+
+- Calculate brand vs. non-brand split: what % of conversions and spend comes from brand terms?
+- If brand represents >60% of conversions: "Account ROAS is inflated by brand traffic. Non-brand CPA is $X vs. brand CPA of $Y — this is the true acquisition cost"
+- If brand and non-brand are mixed in the same campaigns, flag as a structural issue (→ Pass 3)
+
+#### Bid strategy fitness → Pass 3
-These personas feed directly into `/ads-copy` for headline generation and `/ads` for keyword strategy.
+- Does the bid strategy match the campaign goal and data volume?
+- Learning phase stability: are campaigns stuck in "Learning" or "Learning (limited)"?
+- For tCPA/tROAS: is the target realistic given historical data? (>50% gap = choking volume or burning money)
+- Manual bid adjustments (device, location, schedule) fighting Smart Bidding → remove conflicting adjustments
+- **PMax bid strategy:** PMax only supports MAXIMIZE_CONVERSIONS (with optional tCPA) and MAXIMIZE_CONVERSION_VALUE (with optional tROAS). If PMax is on MAXIMIZE_CONVERSIONS with no tCPA cap and CPA is climbing, recommend adding a cap based on historical data
+
+#### Conversion value sanity check → Pass 1
+
+For accounts with mixed-value services, check whether CPA exceeds the likely service value. A $50 CPA on a Board & Train lead (worth $2,000+) is excellent. A $50 CPA on a nail trim (worth $25) is negative ROI — even though it "converted." Read `{data_dir}/business-context.json` if it exists for service value context.
+
+#### Wasted spend calculation
+
+Use the **Wasted Spend Calculation** formula from `references/account-health-scoring.md` — it covers all three waste components (keyword, search term, structural) and includes de-duplication rules to avoid double-counting.
+
+---
+
+### Layer 4: Scale — "How do I get more?" → Pass 2
+
+Only reach this layer after Layers 1-3 are addressed. Scaling broken foundations amplifies waste.
+
+**Budget-constrained winners (Lost IS — Budget):**
+
+Lost IS (Budget) is a capital problem, not a relevance problem: "You're winning auctions but running out of gas."
+
+- For each campaign with budget-lost IS > 20% AND CPA at/below account average → this is the #1 scaling lever. The auction already validates your ads
+- **Do not recommend increasing budget on campaigns with rank-lost IS > 30%.** Fix relevance first
+- Quantify: "Campaign X has 35% budget-lost IS at $45 CPA. Increasing daily budget by $X could capture ~Y additional conversions/month"
+
+**Coverage gaps:**
+- Geographic: locations the business serves but isn't targeting?
+- Dayparting: ads dark during hours customers convert? Only flag if >2x conversion rate difference between best and worst periods
+- Device: segments accidentally excluded or severely underperforming?
+- Audiences: no remarketing lists or customer match segments? These are typically the highest-ROAS audiences — missing them means leaving the easiest conversions on the table
+
+**High-CTR, low-conversion ad groups:**
+
+If an ad group has CTR above campaign average but conversion rate below average, the problem is likely the landing page. Check: does the landing page match intent? Is there a clear CTA?
+
+---
+
+### Layer 5: Growth — "What's next?" → Pass 2 / forward-looking
+
+**Incrementality:**
+- If brand campaigns represent >70% of conversions and non-brand CPA is 3x+ brand CPA, the account is over-dependent on brand traffic. Growth requires making non-brand work, not scaling brand
+- Flag if the account has never tested pausing brand campaigns to measure organic lift
+
+**Channel expansion:**
+- New campaign types: PMax (if not already running), Demand Gen, video
+- New keyword territories / adjacent service areas
+- Competitor conquesting opportunities
+
+Note these as forward-looking recommendations — they give the user a roadmap after fixing the urgent issues
+
+## Phase 2.5: Persona Discovery
+
+Discover 2-3 customer personas from the ad data. This runs in parallel with Phase 3 — it uses only the data already pulled in Phase 1. Read `references/persona-discovery.md` for the full template, derivation rules, and JSON schema.
+
+Key rules:
+- Each persona must be grounded in 5+ actual search terms from the data — no speculative personas
+- Name by behavior ("The Emergency Caller"), not demographics
+- If all search terms look the same, 1-2 personas max. Don't force 3
+- Save to `{data_dir}/personas/{accountId}.json` for downstream skills
## Phase 3: Build Business Context
@@ -363,55 +383,9 @@ Pull as much as possible from the data you already have — only ask the user fo
| `keyword_landscape.long_tail_opportunities` | Converting search terms not yet added as keywords |
| `website` | Ad final URLs (extract root domain from `listAds` data) |
-### Website crawl (kicked off after Phase 1A, results used here)
-
-This crawl starts in the background after Phase 1A (see note in Phase 1A). By the time you reach Phase 3, the results should be ready.
-
-**Step 1: Resolve the website URL**
-
-Find the website URL from Phase 1 data, in priority order:
-1. Ad final URLs from `listAds` — extract the root domain (e.g., `https://example.com`). Normalize to the apex domain (strip `www.` and subdomain prefixes) before frequency-counting across all ads. Use the most common domain.
-2. If no URL found in ad data, ask the user: "What's your website URL?"
-
-**Step 2: Crawl the website**
-
-Issue all `WebFetch` calls in a single tool-use turn so they run in parallel. If any individual fetch fails (404, timeout, blocked), skip that page and continue.
-
-| Page | URL pattern | Why |
-|------|-------------|-----|
-| Homepage | `{root_url}` | Services overview, hero messaging, trust signals, brand voice |
-| About page | `{root_url}/about` | Differentiators, history, team, social proof |
-| Services page | `{root_url}/services` | Full service list, service descriptions |
-| Top ad landing pages | Up to 3 unique final URLs from ads, **excluding any URL that matches the homepage, about, or services pages already being fetched** | What the ads actually link to — offers, CTAs, messaging |
+### Website crawl + extraction
-**Fallback if `/about` or `/services` return 404:** Try one fallback each:
-- About: try `/about-us` (most common variant)
-- Services: try `/our-services` (most common variant)
-
-If the fallback also 404s, move on — don't spider the site.
-
-**Detecting unusable pages:** If a fetched page has fewer than 50 words of visible text (excluding HTML tags, scripts, and navigation), or if the primary content is a login/auth form (email/password fields, "Sign In" as the main heading), treat it as a failed fetch and skip it for extraction.
-
-**Step 3: Extract business context from crawled pages**
-
-Scan the fetched page content for these signals. Merge with what you already inferred from account data — website data fills gaps, account data confirms what's active.
-
-| Field | What to look for on the website |
-|-------|-------------------------------|
-| `services` | Service names from navigation, headings, service cards. **Merge** with services inferred from campaigns — the website may list services not yet advertised |
-| `differentiators` | "Why choose us" sections, hero subheadings, unique value claims (e.g., "Family-owned since 1998", "Same-day service guaranteed") |
-| `social_proof` | Review counts, star ratings, award badges, "As seen in" logos, certifications, years in business, number of customers served |
-| `offers_or_promotions` | Banner offers, hero CTAs with discounts, seasonal promotions, "Free estimate" or "X% off" |
-| `brand_voice` | Tone of headlines and body copy — professional vs casual, technical vs approachable. Capture 3-5 literal phrases from the site that exemplify the tone |
-| `target_audience` | Who the site speaks to — homeowners vs businesses, specific industries, demographic cues |
-| `locations` | Footer addresses, "Areas we serve" pages, location-specific content |
-| `landing_pages` | Map each ad final URL to a summary of what's on that page (headline, primary CTA, offer if any) |
-| `industry` | What the business clearly does — confirm or refine what campaign names suggest |
-| `competitors` | Look for comparison tables or "vs" pages linked from the nav |
-
-**Important:** Only extract from pages you actually retrieved with usable content. If the homepage is all you got, that's fine — it usually has the most signal. Extract in the site's original language — downstream skills handle translation when generating English ad copy.
-
-**If all pages failed or returned no usable content**, skip website extraction entirely and proceed to the full question set below (do not skip any questions).
+Read `references/business-context.md` for the full crawl procedure (URL resolution, page list, fallbacks, extraction fields). The crawl was kicked off after Phase 1B — results should be ready by now.
### What to ask the user
@@ -431,91 +405,89 @@ Present what you inferred from **both** account data and the website crawl, then
### Save the context
-Write the complete business context to `{data_dir}/business-context.json`:
+Write to `{data_dir}/business-context.json` using the schema in `references/business-context.md`. Include `audit_date` (today's date) and `account_id` so future skills know when this was last refreshed.
+
+## Phase 4: Deliver the Audit Report
+
+The report uses the **3-pass structure** — organized by what the user should do, not by what dimension was analyzed. Lead with the verdict and pulse metrics, then the three passes, then personas and questions.
+
+**The #1 rule: no duplication.** Each finding appears in exactly one place.
+
+### Pulse Metrics
+
+Track 3 objective metrics — one per pass. Each has a clear "better" direction and is denominated in something the user already understands.
+
+| Metric | What it measures | Maps to | Better = | How to calculate |
+|--------|-----------------|---------|----------|-----------------|
+| **Waste rate** | % of spend on zero-conversion entities | Pass 1 | Lower | See **Wasted Spend Calculation** in `references/account-health-scoring.md` (3-component formula: keyword + search term + structural waste) |
+| **Demand captured** | Weighted avg impression share on profitable campaigns | Pass 2 | Higher | `avg(search_impression_share)` across campaigns with at least 1 conversion in the period, weighted by spend. If the account has explicit CPA/ROAS targets (from business-context.json), use CPA <= 1.5x target as the profitability filter instead |
+| **CPA** | Cost per conversion | Pass 3 | Lower or stable | `total spend / total conversions` for the period |
+
+Each number means something specific. "Waste dropped from 18% to 11%" tells you Pass 1 actions worked. Each number points to a pass. They're in the user's language — dollars and percentages, not arbitrary scales.
+
+### History persistence
+
+After each audit, append a snapshot to `{data_dir}/audit-history.json`:
```json
{
- "business_name": "",
- "industry": "",
- "website": "",
- "services": [],
- "locations": [],
- "target_audience": "",
- "brand_voice": {
- "tone": "",
- "words_to_avoid": [],
- "words_to_use": []
- },
- "differentiators": [],
- "competitors": [],
- "seasonality": {
- "peak_months": [],
- "slow_months": [],
- "seasonal_hooks": []
- },
- "keyword_landscape": {
- "high_intent_terms": [],
- "competitive_terms": [],
- "long_tail_opportunities": []
- },
- "social_proof": [],
- "offers_or_promotions": [],
- "landing_pages": {},
- "notes": "",
- "audit_date": "",
- "account_id": ""
+ "history": [
+ {
+ "date": "2026-04-11",
+ "date_range": "2026-03-12 to 2026-04-11",
+ "account_id": "7521406707",
+ "total_spend": 1431.48,
+ "total_conversions": 72,
+ "metrics": {
+ "waste_rate": 11.3,
+ "demand_captured": 42.7,
+ "cpa": 19.88
+ },
+ "top_actions": [
+ "Paused 'free dog food' keyword ($120 waste)",
+ "Budget-lost IS 40% on Tukwila Search at $14 CPA"
+ ]
+ }
+ ]
}
```
-Include `audit_date` (today's date) and `account_id` so future skills know when this was last refreshed.
-
-## Phase 4: Deliver the Audit Report
-
-The report follows an **onion structure** — lead with the verdict, then actions, then evidence. The reader should get the full picture in the first 10 lines, and only needs to keep reading if they want the supporting data.
+**On first audit:** Create the file. Show raw values with no comparison.
-**The #1 rule: no duplication.** Each finding appears in exactly one place. The scorecard summarizes, the actions tell you what to do, the evidence shows why. If something is in the scorecard's "Key Finding" column, don't repeat it in the evidence section.
+**On subsequent audits:** Load the previous entry and compute trends:
+- Improved (moved in "better" direction by >5% relative) = show improvement with previous value
+- Unchanged (moved <5% either way) = stable
+- Worsened (moved in wrong direction by >5%) = flag with warning
### Report structure
```
# [Business Name] — Ads Audit
-**[Score]/100 · $X,XXX spent (30d) · XX conversions at $XX CPA**
+**[Date range] · $X,XXX spent · XX conversions · $XX CPA**
+Waste: X% · Demand captured: X% · CPA: $X
+[If previous audit exists: show (was Y%) for each metric]
[If scoped] Scoped to: [description]
[2-3 sentence verdict. What's working, what's broken, and the single biggest
opportunity in dollar terms. This paragraph should be enough for someone who
won't read further.]
-## What to Fix (in order)
+## Stop Wasting (Pass 1)
+1. **[Action]** — saves $X/month
+2. **[Action]** — saves $X/month
+3. **[Action]** — saves $X/month
-1. **[Specific action]** — [1-line why + expected dollar/conversion impact]
-2. **[Specific action]** — [1-line why + expected impact]
-3. **[Specific action]** — [1-line why + expected impact]
+## Capture More (Pass 2)
+1. **[Action]** — est. +X conversions/month at $Y CPA
+2. **[Action]** — est. +X conversions/month
+3. **[Action]** — est. +X conversions/month
-Run `/ads` to execute any of these.
-
-## Scorecard
-
-| Dimension | Score | Key Finding |
-|-----------|-------|-------------|
-| Conversion tracking | X/5 | [one line] |
-| Campaign structure | X/5 | [one line] |
-| Keyword health | X/5 | [one line] |
-| Search term quality | X/5 | [one line] |
-| Ad copy | X/5 | [one line] |
-| Impression share | X/5 | [one line] |
-| Spend efficiency | X/5 | [one line] |
-
-## Evidence
+## Fix Fundamentals (Pass 3)
+1. **[Action]** — est. X% CPC reduction on $Y/month spend
+2. **[Action]** — [impact]
+3. **[Action]** — [impact]
-[Only include dimensions scoring 0-2. Each dimension gets ONE compact block.
-Do NOT repeat what's already in the scorecard or actions — add the supporting
-data that explains the score.]
-
-### [Dimension] (X/5)
-[2-4 lines of data: the specific keywords, search terms, or metrics that
-drove the score. Top 3 examples max — not exhaustive lists. End with the
-fix if it wasn't already an action item above.]
+Run `/ads` to execute any of these.
## Personas
@@ -533,20 +505,16 @@ Max 2-3 questions. Don't ask what you can infer from the data.]
- **Specific:** "Pause keyword 'free dog food' — $847 spent, 0 conversions" not "Review underperforming keywords"
- **Quantified:** Include the spend, impressions, or conversions at stake
-- **Prioritized:** Highest-impact items first. Stopping waste > starting new things
-- **Actionable with /ads:** Every recommendation should be something the user can execute immediately using the `/ads` skill
- **Dollar-denominated:** Express impact as "save $X/month" or "gain X conversions/month at $Y CPA"
+- **Actionable with /ads:** Every recommendation should be executable via `/ads`
### Output discipline
-These rules prevent the bloated, repetitive reports that make audits hard to read:
-
-1. **No standalone "Key Numbers" section.** The headline already has spend, conversions, and CPA. Don't repeat them.
-2. **No standalone "Wasted Spend Analysis" section.** Waste data belongs in the relevant Evidence dimension (keyword health or search term quality). Mention the total in the verdict paragraph.
-3. **No standalone "Impression Share Analysis" section.** The diagnosis belongs in the scorecard line + Evidence block if IS scored 0-2.
-4. **Max 3 examples per finding.** Show the top 3 by spend, not an exhaustive list. The user can drill deeper with `/ads`.
-5. **Evidence sections are for data, not narrative.** Don't explain what QS is or how impression share works — just show the numbers that matter.
-6. **The entire report should fit in ~60-80 lines of markdown.** If you're over 100 lines, you're duplicating or over-explaining.
+1. **Empty passes are fine.** If a pass finds no issues, show "No issues found" and move on. Don't fabricate findings.
+2. **Max 3 items per pass.** If you found 10 things, pick the top 3 by dollar impact. The user can re-audit after fixing those.
+3. **Max 3 examples per finding.** Show the top 3 by spend, not an exhaustive list.
+4. **No standalone analysis sections.** Don't create separate "Wasted Spend Analysis" or "Impression Share Analysis" sections. Findings belong in their pass.
+5. **The entire report should fit in ~60-80 lines of markdown.** If you're over 100 lines, you're duplicating or over-explaining.
### Conditional handoff (pick the single most relevant one)
@@ -554,10 +522,12 @@ After the report, add ONE handoff based on the biggest issue found:
| Condition | Handoff |
|-----------|---------|
-| Ad copy scored 0-2 | Suggest `/ads-copy` for RSA variants |
-| Impression share scored 0-2 | Suggest `/ads` for bid optimization |
+| Ad copy issues dominate Pass 3 | Suggest `/ads-copy` for RSA variants |
+| Rank-lost IS > 30% | Suggest `/ads` for QS and relevance improvements (not budget) |
+| Budget-lost IS > 20% on profitable campaigns | Suggest `/ads` for budget optimization |
| 3+ converting search terms not yet keywords | Offer to add them via `/ads` |
-| Wasted spend > 15% | Offer to pause/negative via `/ads` |
+| Waste rate > 15% | Offer to pause/negative via `/ads` |
+| Brand >60% of conversions | Flag brand dependency risk; suggest non-brand strategy |
| High CTR but low conversion rate | Suggest landing page audit |
Don't list all possible handoffs — pick the one that matches the #1 action item.
@@ -570,5 +540,5 @@ Don't list all possible handoffs — pick the one that matches the #1 action ite
4. **Prioritize by money.** The biggest waste or biggest opportunity comes first.
5. **Save the context.** Always write `business-context.json` — this is the handoff to every other ads skill.
6. **Don't fix things here.** This skill diagnoses and recommends. The user executes fixes with `/ads`. Offer to switch to `/ads` for implementation.
-7. **Score everything.** Every dimension gets a 0-5 score. The overall health score gives the user a single number to track over time. Re-auditing in 30 days should show improvement.
+7. **Track progress.** Always compute and persist pulse metrics. On re-audits, show trends.
8. **Name names.** Every finding should reference specific campaigns, keywords, ad groups, or search terms. "Some keywords are underperforming" is not an audit finding — "$423 spent on 'free plumbing advice' with 0 conversions" is.
diff --git a/google-ads/ads-audit/references/account-health-scoring.md b/google-ads/ads-audit/references/account-health-scoring.md
index 8456a710..5bf6630b 100644
--- a/google-ads/ads-audit/references/account-health-scoring.md
+++ b/google-ads/ads-audit/references/account-health-scoring.md
@@ -1,35 +1,30 @@
-# Account Health Scoring Framework
+# Account Health — Diagnostic Reference
-Structured scoring methodology for Google Ads account audits. Seven health dimensions, each scored 0-5, with weighted rollup to a 0-100 overall score.
+Thresholds, red flags, interpretation matrices, and benchmarks for Google Ads account audits. Use these to determine severity of findings and assign them to the right pass (Stop Wasting, Capture More, or Fix Fundamentals).
---
-## Health Dimensions Overview
+## Audit Areas Overview
-| # | Dimension | Weight | What It Measures |
-|---|-----------|--------|-----------------|
-| 1 | Conversion Tracking | 20% | Tracking completeness and sophistication |
-| 2 | Campaign Structure | 15% | Organization, segmentation, budget logic |
-| 3 | Keyword Health | 20% | Quality scores, match types, zombie keywords |
-| 4 | Search Term Quality | 15% | Query relevance, negative coverage, mining |
-| 5 | Ad Copy | 10% | RSA quantity, variety, and performance |
-| 6 | Impression Share | 10% | Budget and rank signal interpretation |
-| 7 | Spend Efficiency | 10% | Wasted spend, CPA, concentration risk |
+| Area | Layer | What to Check |
+|------|-------|---------------|
+| Signal Quality | 1: Signals | Tracking completeness, enhanced conversions, consent mode, data density for Smart Bidding |
+| Campaign Structure | 2: Relevance | Organization, segmentation, budget logic, PMax cannibalization |
+| Keyword Health | 2: Relevance | Quality scores, match types, zombie keywords, wasted spend |
+| Search Term Quality | 2: Relevance | Query relevance, negative coverage, mining opportunities |
+| Ad Copy & Creative | 2: Relevance | RSA quantity, variety, asset health, extensions, PMax completeness |
+| Impression Share | 2/4: Relevance/Scale | Rank-lost IS = Layer 2 relevance problem; Budget-lost IS = Layer 4 scaling opportunity — different problems, different fixes |
+| Spend Efficiency | 3: Efficiency | Wasted spend, CPA, brand vs non-brand split, concentration risk |
---
-## Dimension 1: Conversion Tracking (Weight: 20%)
+## Signal Quality
-| Score | Level | Criteria |
-|-------|-------|----------|
-| 0 | None | No conversion tracking installed |
-| 1 | Basic | Tag fires but no values assigned; only 1 conversion action |
-| 2 | Partial | Multiple conversion actions with values, but gaps: missing phone calls OR form submissions OR key pages |
-| 3 | Solid | All key actions tracked (form, phone, purchase); values assigned; conversion window set correctly; Consent Mode v2 implemented (mandatory for EU since March 2024) |
-| 4 | Advanced | Score 3 + enhanced conversions enabled; conversion linker tag present; GCLID auto-tagging on; Consent Mode v2 verified across all regions |
-| 5 | Best-in-class | Score 4 + offline conversion import OR store visit tracking; server-side tagging implemented; data-driven attribution model |
+*Layer 1 — "Can I trust the data?"*
-### Conversion Tracking Red Flags
+If signals are broken, every decision downstream is built on lies — and Smart Bidding can't optimize what it can't measure.
+
+### Red Flags
| Signal | Severity | What It Means |
|--------|----------|---------------|
@@ -38,19 +33,15 @@ Structured scoring methodology for Google Ads account audits. Seven health dimen
| All conversions = "Website" (no action names) | High | Default tracking, no meaningful segmentation |
| "Include in conversions" set to YES for micro-conversions | Medium | Inflated conversion counts, misleading CPA |
| Last-click attribution on any campaigns | High | Deprecated since 2023 — data-driven attribution (DDA) is now the only model for new conversion actions. Migrate existing conversion actions to DDA immediately |
+| Campaign using tCPA/tROAS with <15 conversions/month | High | Insufficient data density — Smart Bidding can't learn. Need 30+ for tCPA, 50+ for tROAS |
+| No Consent Mode v2 with EU traffic | High | Degraded conversion modeling in privacy-regulated markets. Bid strategies underperform |
+| Enhanced conversions not enabled | Medium | Cross-device and cross-browser attribution gaps. Smart Bidding missing signal |
---
-## Dimension 2: Campaign Structure (Weight: 15%)
+## Campaign Structure
-| Score | Level | Criteria |
-|-------|-------|----------|
-| 0 | Chaotic | 1 campaign, 1 ad group, 200+ keywords of mixed intent |
-| 1 | Minimal | Multiple campaigns but no logical organization; ad groups have 50+ keywords spanning unrelated themes |
-| 2 | Basic | Campaigns organized by service/product line; ad groups still too broad (30-50 keywords) |
-| 3 | Good | Properly themed ad groups (10-20 keywords each); logical campaign splits by service/geo; match types considered |
-| 4 | Strong | Score 3 + separate brand campaign; geo-targeted campaigns where relevant; budget allocated by priority |
-| 5 | Excellent | Score 4 + funnel-stage separation (brand/non-brand/competitor/remarketing); proper budget allocation ratios; campaign experiments running |
+*Layer 2 — "Am I in the right auctions?"*
### Structure Assessment Checklist
@@ -62,19 +53,13 @@ Structured scoring methodology for Google Ads account audits. Seven health dimen
| Campaign naming convention | Consistent pattern | No pattern (e.g., "Campaign 1", "test") |
| Budget distribution | Proportional to priority | Equal across all campaigns regardless of performance |
| Location targeting | Set per campaign need | All campaigns target same broad area |
+| PMax cannibalization | PMax excluded from brand terms or brand IS stable | PMax running alongside Search with declining brand IS |
---
-## Dimension 3: Keyword Health (Weight: 20%)
+## Keyword Health
-| Score | Level | Criteria |
-|-------|-------|----------|
-| 0 | Failing | Average QS <4; >50% zombie keywords; no match type strategy |
-| 1 | Poor | Average QS 4-5; 30-50% zombie keywords; broad match without Smart Bidding or negatives |
-| 2 | Below Average | Average QS 5-6; 20-30% zombie keywords; broad match with Smart Bidding but insufficient negatives |
-| 3 | Good | Average QS 6-7; <20% zombie keywords; intentional match type strategy; negatives in place |
-| 4 | Strong | Average QS 7-8; <10% zombie keywords; intentional match type strategy aligned with Smart Bidding |
-| 5 | Excellent | Average QS 8+; <5% zombie keywords; tightly themed ad groups aligned to Smart Bidding signals; comprehensive negative coverage |
+*Layer 2 — "Am I in the right auctions?"*
### Keyword Sub-Metric Thresholds
@@ -96,16 +81,9 @@ Structured scoring methodology for Google Ads account audits. Seven health dimen
---
-## Dimension 4: Search Term Quality (Weight: 15%)
+## Search Term Quality
-| Score | Level | Criteria |
-|-------|-------|----------|
-| 0 | Unmonitored | Never reviewed; no negative keywords; broad match with no controls |
-| 1 | Neglected | Reviewed once; <10 negative keywords; relevance <60% |
-| 2 | Basic | Quarterly review; 10-30 negatives; relevance 60-75% |
-| 3 | Managed | Monthly review; 30-100 negatives; relevance 75-85%; obvious irrelevants blocked |
-| 4 | Active | Bi-weekly review; 100+ negatives organized in lists; relevance 85-90%; mining opportunities captured |
-| 5 | Optimized | Weekly review; comprehensive negative lists by theme; relevance >90%; all converting terms added as exact keywords; shared negative lists across campaigns |
+*Layer 2 — "Am I in the right auctions?"*
### Search Term Relevance Thresholds
@@ -128,18 +106,13 @@ Structured scoring methodology for Google Ads account audits. Seven health dimen
---
-## Dimension 5: Ad Copy (Weight: 10%)
+## Ad Copy & Creative
+
+*Layer 2 — "Am I fit to compete in the auctions I'm entering?"*
-| Score | Level | Criteria |
-|-------|-------|----------|
-| 0 | Missing | Ad groups with 0 or 1 active ad; no RSAs |
-| 1 | Minimal | 1 RSA per ad group; only 3-5 headlines; ad strength "Poor" |
-| 2 | Basic | 1 RSA per ad group; 6-8 headlines; ad strength "Average" |
-| 3 | Good | 1-2 RSAs per ad group; 8-11 headlines from 3+ angles; ad strength "Good" |
-| 4 | Strong | 2 RSAs per ad group for testing; 11-15 headlines; 5+ angles; ad strength "Good" to "Excellent" |
-| 5 | Excellent | Score 4 + active A/B tests running; performance data-driven pinning; CTR above position-adjusted benchmark |
+In the RSA + Smart Bidding era, creative variety is how Google's ML finds the right audience segments. Missing assets reduce Ad Rank and limit the algorithm's ability to optimize.
-### Ad Copy Sub-Metrics
+### Ad Copy & Creative Sub-Metrics
| Sub-Metric | Poor | Average | Good | Excellent |
|------------|------|---------|------|-----------|
@@ -149,21 +122,22 @@ Structured scoring methodology for Google Ads account audits. Seven health dimen
| Ad strength distribution | >50% Poor | >50% Average | >50% Good | >50% Excellent |
| CTR vs. position benchmark | >30% below | 10-30% below | At benchmark | Above benchmark |
| Descriptions with CTA | 0% | 25-50% | 50-75% | 75%+ |
+| Extension coverage | None | 1-2 types | 3-4 types | Full suite |
+| PMax asset completeness | Missing asset types | Partial | Most types | All types with variety |
---
-## Dimension 6: Impression Share (Weight: 10%)
+## Impression Share
+
+**Data limit:** `getImpressionShare` supports max 90 days (not 365 like other tools). For GAQL impression share queries, the same 90-day practical limit applies. Do not use `LAST_365_DAYS` for impression share data.
+
+*Diagnosed across two layers:*
+- **Lost IS (Rank)** = Layer 2 relevance problem. The auction is telling you your Ad Rank is low. Fix with better ads, tighter themes, better landing pages — not more money.
+- **Lost IS (Budget)** = Layer 4 scaling opportunity. You're winning auctions but running out of gas. Fix with more budget or narrower targeting.
-| Score | Level | Criteria |
-|-------|-------|----------|
-| 0 | Invisible | Search IS <20%; losing >80% of eligible impressions |
-| 1 | Struggling | Search IS 20-40%; high losses on both budget and rank |
-| 2 | Below Average | Search IS 40-60%; one major loss driver (budget OR rank) |
-| 3 | Competitive | Search IS 60-75%; budget-lost IS <20% and rank-lost IS <30% |
-| 4 | Strong | Search IS 75-90%; budget-lost IS <10% and rank-lost IS <15% |
-| 5 | Dominant | Search IS >90%; minimal losses on both dimensions |
+This split is the most important insight in the audit. Treating both as a single "impression share problem" gives bad advice — telling someone with a relevance problem to spend more money just burns money faster.
-### Budget-Lost IS Interpretation
+### Budget-Lost IS Interpretation (Layer 4 — Scale)
| Budget-Lost IS | Severity | Meaning |
|---------------|----------|---------|
@@ -172,12 +146,12 @@ Structured scoring methodology for Google Ads account audits. Seven health dimen
| 10-20% | Acceptable | Minor constraint; may be intentional budget cap |
| <10% | Good | Budget is not a limiting factor |
-### Rank-Lost IS Interpretation
+### Rank-Lost IS Interpretation (Layer 2 — Relevance)
| Rank-Lost IS | Severity | Meaning |
|-------------|----------|---------|
-| >50% | Crisis | Ads rarely showing in competitive positions; QS or bid fundamentally broken |
-| 30-50% | Needs Work | Consistently outranked; improve QS, bids, or ad relevance |
+| >50% | Crisis | Ads rarely showing in competitive positions; QS or bid fundamentally broken. Do NOT spend more — fix relevance first |
+| 30-50% | Needs Work | Consistently outranked; improve QS, ad relevance, or landing page experience |
| 15-30% | Competitive | Normal competitive loss; optimize incrementally |
| <15% | Strong | Winning most eligible auctions |
@@ -185,28 +159,29 @@ Structured scoring methodology for Google Ads account audits. Seven health dimen
| | Rank-Lost IS LOW (<20%) | Rank-Lost IS HIGH (>20%) |
|---|------------------------|--------------------------|
-| **Budget-Lost IS LOW (<15%)** | **Healthy** -- Optimizing at the margins. Focus on bid strategy and new keyword expansion. | **QS / Bid Problem** -- Ads not competitive. Improve ad relevance, landing pages, or increase bids. Check QS components. |
-| **Budget-Lost IS HIGH (>15%)** | **Pure Budget Problem** -- Ads are competitive when shown. Increase budget, narrow geo targeting, or daypart to stretch budget. | **Structural Problem** -- Wrong keywords entirely. Audience too broad, poor campaign structure. Rebuild targeting from scratch. |
+| **Budget-Lost IS LOW (<15%)** | **Healthy** -- Optimizing at the margins. Focus on bid strategy and new keyword expansion. | **Relevance Problem (Layer 2 fix)** -- Ads not competitive. Improve ad relevance, landing pages, or check QS components. Do not increase budget. |
+| **Budget-Lost IS HIGH (>15%)** | **Capital Problem (Layer 4 fix)** -- Ads are competitive when shown. Increase budget, narrow geo targeting, or daypart to stretch budget. | **Structural Problem (Layer 2 fix)** -- Wrong keywords entirely. Audience too broad, poor campaign structure. Rebuild targeting from scratch. |
---
-## Dimension 7: Spend Efficiency (Weight: 10%)
+## Spend Efficiency
-| Score | Level | Criteria |
-|-------|-------|----------|
-| 0 | Burning | >30% wasted spend; CPA >3x industry benchmark; no conversion data |
-| 1 | Poor | 20-30% wasted spend; CPA 2-3x benchmark; top spenders not converting |
-| 2 | Below Average | 15-20% wasted spend; CPA 1.5-2x benchmark |
-| 3 | Average | 10-15% wasted spend; CPA within 1-1.5x benchmark; top 20% keywords drive 50%+ conversions |
-| 4 | Good | 5-10% wasted spend; CPA at or below benchmark; strong conversion concentration |
-| 5 | Excellent | <5% wasted spend; CPA well below benchmark; top 20% keywords drive 60%+ conversions; no keyword spending >2x account CPA with 0 conversions |
+*Layer 3 — "Am I spending wisely?"*
### Wasted Spend Calculation
+Wasted spend is the sum of three components:
+
```
-Wasted Spend % = (Spend on keywords with 0 conversions AND >10 clicks) / Total Spend x 100
+Keyword waste = Spend on keywords with 0 conversions AND spend > 2x account avg CPA
+Search term waste = Spend on search terms with 10+ clicks AND 0 conversions (data-only filter — no subjective scoring)
+Structural waste = Spend on Display Network clicks in Search campaigns where display clicks > 20 AND 0 display conversions
+
+Wasted Spend % = (keyword waste + search term waste + structural waste) / Total Spend x 100
```
+**De-duplication:** Search term waste and keyword waste can overlap (a wasted keyword triggers wasted search terms). To avoid double-counting, calculate keyword waste first, then only count search term waste from search terms that don't map to already-counted wasted keywords.
+
| Wasted Spend % | Severity | Monthly Waste at $10k Spend |
|---------------|----------|-----------------------------|
| >30% | Critical | >$3,000/month burned |
@@ -215,6 +190,19 @@ Wasted Spend % = (Spend on keywords with 0 conversions AND >10 clicks) / Total S
| 5-10% | Low | $500-$1,000/month |
| <5% | Healthy | <$500/month |
+### Brand vs. Non-Brand Segmentation
+
+Many accounts show great overall ROAS, but the majority comes from brand traffic — you're paying Google a tax on existing customers, not acquiring new ones. This analysis is critical for understanding true acquisition efficiency.
+
+| Brand % of Conversions | Interpretation |
+|------------------------|---------------|
+| >80% | Over-dependent on brand. Account ROAS is misleading — non-brand performance is likely poor. Growth requires making non-brand work |
+| 60-80% | Brand-heavy. Report non-brand CPA separately — this is the true acquisition cost |
+| 40-60% | Healthy mix. Both channels contributing meaningfully |
+| <40% | Non-brand dominant. Verify brand isn't being cannibalized by PMax or competitors |
+
+Always report: "Overall CPA is $X, but brand CPA is $Y and non-brand CPA is $Z." If brand and non-brand aren't in separate campaigns, flag as a structural issue (→ Pass 3).
+
### Spend Concentration Analysis
| Metric | Healthy | Warning | Critical |
@@ -222,62 +210,19 @@ Wasted Spend % = (Spend on keywords with 0 conversions AND >10 clicks) / Total S
| Top 20% keywords' share of conversions | >50% | 30-50% | <30% |
| Top 20% keywords' share of spend | <50% | 50-70% | >70% with low conversion share |
| Single keyword share of total spend | <15% | 15-30% | >30% (concentration risk) |
-| Keywords spending >1x account CPA with 0 conversions | 0-2 | 3-5 | >5 |
+| Keywords spending >2x account CPA with 0 conversions | 0-2 | 3-5 | >5 |
---
-## Overall Health Score Calculation
-
-### Formula
-
-```
-Overall Score = (D1 x 0.20 + D2 x 0.15 + D3 x 0.20 + D4 x 0.15 + D5 x 0.10 + D6 x 0.10 + D7 x 0.10) / 5 x 100
-```
-
-Where D1-D7 are the dimension scores (0-5).
+## Pulse Metrics — What to Track
-### Example Calculation
+Instead of a composite score, the audit tracks 3 objective metrics:
-| Dimension | Score | Weight | Weighted |
-|-----------|-------|--------|----------|
-| Conversion Tracking | 3 | 0.20 | 0.60 |
-| Campaign Structure | 2 | 0.15 | 0.30 |
-| Keyword Health | 4 | 0.20 | 0.80 |
-| Search Term Quality | 3 | 0.15 | 0.45 |
-| Ad Copy | 2 | 0.10 | 0.20 |
-| Impression Share | 3 | 0.10 | 0.30 |
-| Spend Efficiency | 3 | 0.10 | 0.30 |
-| **Total** | | | **2.95** |
-
-Overall Score = 2.95 / 5 x 100 = **59 / 100** (Needs Work)
-
----
-
-## Severity Classification
-
-| Score Range | Classification | Typical Account Profile | Urgency |
-|-------------|---------------|------------------------|---------|
-| 0-30 | Critical | No tracking, chaotic structure, massive waste. Money is actively burning. | Fix this week. Every day costs money. |
-| 31-50 | Needs Significant Work | Basic tracking but major structural gaps. Likely 30-50% of spend is wasted. | Fix within 2 weeks. Prioritize highest-waste areas. |
-| 51-70 | Needs Work | Tracking works, structure is OK, but optimization gaps. Common for unmanaged or self-managed accounts. | Fix within 30 days. Methodical improvement plan. |
-| 71-85 | Good | Well-managed account with room for optimization. Typical of accounts with active management. | Ongoing optimization. Quarterly deep reviews. |
-| 86-100 | Strong | Well-optimized account. Marginal gains from here. | Maintain. Focus on scaling and expansion. |
-
----
-
-## Priority Action Matrix
-
-For each dimension scored below 3, the single highest-impact fix:
-
-| Dimension | Score 0 Fix | Score 1 Fix | Score 2 Fix |
-|-----------|------------|------------|------------|
-| Conversion Tracking | Install Google Tag + at least 1 conversion action | Add conversion values; track all key actions (form, phone, purchase) | Fill coverage gaps; enable enhanced conversions |
-| Campaign Structure | Split into service-based campaigns with 10-20 keyword ad groups | Reorganize ad groups by theme; separate brand from non-brand | Tighten ad groups to 10-20 keywords; add geo targeting |
-| Keyword Health | Pause all QS <3 keywords; add negative keywords; reduce to 10-20 per ad group | Focus on QS 4-5 keywords: improve ad relevance and landing pages | Add exact match for top converters; pause zombie keywords |
-| Search Term Quality | Run first-ever search term review; add 20+ obvious negatives | Build negative keyword lists by theme; block top wasters | Set up bi-weekly review cadence; mine converting terms |
-| Ad Copy | Create RSA with 8+ headlines for every ad group | Add headlines to reach 8+; ensure 3+ distinct angles | Add second RSA for A/B testing; improve headline variety |
-| Impression Share | Check if budget is depleting before noon; adjust bids down or narrow targeting | Identify top budget-loss campaign; increase budget or narrow geo/schedule | Improve QS on rank-lost keywords; test bid strategies |
-| Spend Efficiency | Pause all keywords with spend >1x account CPA and 0 conversions immediately | Set max CPC caps; pause keywords with >20 clicks and 0 conversions | Reallocate budget from low-efficiency to high-efficiency keywords |
+| Metric | What it measures | Better = | Severity thresholds |
+|--------|-----------------|----------|---------------------|
+| **Waste rate** | % of spend on zero-conversion entities | Lower | >20% critical, 10-20% needs work, 5-10% OK, <5% healthy |
+| **Demand captured** | Weighted avg IS on profitable campaigns | Higher | <30% critical, 30-50% needs work, 50-70% OK, >70% strong |
+| **CPA** | Cost per conversion | Lower/stable | Compare to industry benchmarks below |
---
@@ -286,26 +231,41 @@ For each dimension scored below 3, the single highest-impact fix:
```
START
|
-1. Check Conversion Tracking (Dimension 1)
- +-- Score 0-1? --> STOP. Fix tracking before anything else.
- | No point optimizing what you cannot measure.
- +-- Score 2+? --> Continue
+LAYER 1: SIGNALS
+|
+1. Gate check: Is tracking working?
+ +-- Hard stop? --> STOP. Fix tracking before anything else.
+ +-- Flags? --> Note them, continue
+|
+LAYER 2: RELEVANCE
+|
+2. Pre-checks (location intent, search partners, display network) --> Pass 1
+3. Campaign structure, keyword health, search terms, ad copy
+ +-- Waste findings --> Pass 1 (stop the bleeding)
+ +-- Structural fixes --> Pass 3 (fix fundamentals)
+ +-- PMax running? --> Check cannibalization, asset completeness
+ +-- Rank-lost IS > 30%? --> Pass 3, do NOT recommend more budget
+|
+LAYER 3: EFFICIENCY
+|
+4. Impression share interpretation + spend efficiency
+ +-- Brand vs non-brand segmentation
+ +-- Bid strategy fitness
+ +-- Conversion value sanity check
|
-2. Assess Campaign Structure (Dimension 2)
- +-- Score 0-1? --> Restructure before optimizing keywords/ads.
- +-- Score 2+? --> Continue
+LAYER 4: SCALE
|
-3. Evaluate Keyword Health (Dimension 3) + Search Terms (Dimension 4)
- +-- Run in parallel. These inform each other.
+5. Budget-constrained winners (budget-lost IS on profitable campaigns) --> Pass 2
+ +-- Coverage gaps (geo, dayparting, device) --> Pass 2
+ +-- High-CTR low-conversion ad groups --> Pass 2
|
-4. Review Ad Copy (Dimension 5)
- +-- Only after keywords are stable. No point writing ads for bad keywords.
+LAYER 5: GROWTH
|
-5. Analyze Impression Share (Dimension 6) + Spend Efficiency (Dimension 7)
- +-- These are outcome metrics. Fix inputs (1-5) before worrying about outputs.
+6. Incrementality + expansion opportunities --> Pass 2 / forward-looking
|
-6. Calculate Overall Score
-7. Generate Priority Action Plan (top fix per dimension scoring <3)
+7. Compute pulse metrics (waste rate, demand captured, CPA)
+8. Persist to audit-history.json
+9. Generate 3-pass report (max 3 items per pass)
|
END
```
@@ -314,7 +274,7 @@ END
## Industry CPA Benchmarks
-Reference benchmarks for evaluating Dimension 7 (Spend Efficiency):
+Reference benchmarks for evaluating spend efficiency:
| Industry | Avg CPA (Search) | Good CPA | Excellent CPA |
|----------|-----------------|----------|---------------|
diff --git a/google-ads/ads-audit/references/business-context.md b/google-ads/ads-audit/references/business-context.md
new file mode 100644
index 00000000..67b4befc
--- /dev/null
+++ b/google-ads/ads-audit/references/business-context.md
@@ -0,0 +1,91 @@
+# Business Context — Website Crawl & Data Collection
+
+This reference covers the website crawl procedure and business context JSON schema used by the `/ads-audit` skill.
+
+## Website Crawl
+
+### Step 1: Resolve the website URL
+
+Find the website URL from Phase 1 data, in priority order:
+1. Ad final URLs from `listAds` — extract the root domain (e.g., `https://example.com`). Normalize to the apex domain (strip `www.` and subdomain prefixes) before frequency-counting across all ads. Use the most common domain.
+2. If no URL found in ad data, ask the user: "What's your website URL?"
+
+### Step 2: Crawl the website
+
+Issue all `WebFetch` calls in a single tool-use turn so they run in parallel. If any individual fetch fails (404, timeout, blocked), skip that page and continue.
+
+| Page | URL pattern | Why |
+|------|-------------|-----|
+| Homepage | `{root_url}` | Services overview, hero messaging, trust signals, brand voice |
+| About page | `{root_url}/about` | Differentiators, history, team, social proof |
+| Services page | `{root_url}/services` | Full service list, service descriptions |
+| Top ad landing pages | Up to 3 unique final URLs from ads, **excluding any URL that matches the homepage, about, or services pages already being fetched** | What the ads actually link to — offers, CTAs, messaging |
+
+**Fallback if `/about` or `/services` return 404:** Try one fallback each:
+- About: try `/about-us` (most common variant)
+- Services: try `/our-services` (most common variant)
+
+If the fallback also 404s, move on — don't spider the site.
+
+**Detecting unusable pages:** If a fetched page has fewer than 50 words of visible text (excluding HTML tags, scripts, and navigation), or if the primary content is a login/auth form (email/password fields, "Sign In" as the main heading), treat it as a failed fetch and skip it for extraction.
+
+### Step 3: Extract business context from crawled pages
+
+Scan the fetched page content for these signals. Merge with what you already inferred from account data — website data fills gaps, account data confirms what's active.
+
+| Field | What to look for on the website |
+|-------|-------------------------------|
+| `services` | Service names from navigation, headings, service cards. **Merge** with services inferred from campaigns — the website may list services not yet advertised |
+| `differentiators` | "Why choose us" sections, hero subheadings, unique value claims (e.g., "Family-owned since 1998", "Same-day service guaranteed") |
+| `social_proof` | Review counts, star ratings, award badges, "As seen in" logos, certifications, years in business, number of customers served |
+| `offers_or_promotions` | Banner offers, hero CTAs with discounts, seasonal promotions, "Free estimate" or "X% off" |
+| `brand_voice` | Tone of headlines and body copy — professional vs casual, technical vs approachable. Capture 3-5 literal phrases from the site that exemplify the tone |
+| `target_audience` | Who the site speaks to — homeowners vs businesses, specific industries, demographic cues |
+| `locations` | Footer addresses, "Areas we serve" pages, location-specific content |
+| `landing_pages` | Map each ad final URL to a summary of what's on that page (headline, primary CTA, offer if any) |
+| `industry` | What the business clearly does — confirm or refine what campaign names suggest |
+| `competitors` | Look for comparison tables or "vs" pages linked from the nav |
+
+**Important:** Only extract from pages you actually retrieved with usable content. If the homepage is all you got, that's fine — it usually has the most signal. Extract in the site's original language — downstream skills handle translation when generating English ad copy.
+
+**If all pages failed or returned no usable content**, skip website extraction entirely and proceed to the full question set (do not skip any questions).
+
+## Business Context JSON Schema
+
+Write the complete business context to `{data_dir}/business-context.json`:
+
+```json
+{
+ "business_name": "",
+ "industry": "",
+ "website": "",
+ "services": [],
+ "locations": [],
+ "target_audience": "",
+ "brand_voice": {
+ "tone": "",
+ "words_to_avoid": [],
+ "words_to_use": []
+ },
+ "differentiators": [],
+ "competitors": [],
+ "seasonality": {
+ "peak_months": [],
+ "slow_months": [],
+ "seasonal_hooks": []
+ },
+ "keyword_landscape": {
+ "high_intent_terms": [],
+ "competitive_terms": [],
+ "long_tail_opportunities": []
+ },
+ "social_proof": [],
+ "offers_or_promotions": [],
+ "landing_pages": {},
+ "notes": "",
+ "audit_date": "",
+ "account_id": ""
+}
+```
+
+Include `audit_date` (today's date) and `account_id` so future skills know when this was last refreshed.
diff --git a/google-ads/ads-audit/references/persona-discovery.md b/google-ads/ads-audit/references/persona-discovery.md
new file mode 100644
index 00000000..4921f07b
--- /dev/null
+++ b/google-ads/ads-audit/references/persona-discovery.md
@@ -0,0 +1,60 @@
+# Persona Discovery
+
+Discover 2-3 customer personas from the ad data. This runs in parallel with business context questions — it uses only the data already pulled in Phase 1.
+
+## Data Sources for Persona Construction
+
+| Source | What it reveals | How to access |
+|--------|----------------|---------------|
+| Search terms | What customers actually search for — their language, pain points, urgency | `getSearchTermReport` from Phase 1 |
+| Converting keywords | What they buy — the terms that lead to conversions reveal purchase intent | `getKeywords` filtered to converting |
+| Ad group themes | How the business segments its services — each theme may serve a different persona | Ad group data from Phase 1 |
+| Landing page URLs | Where they land — different pages suggest different customer journeys | `listAds` final URLs from Phase 1 |
+| Geographic data | Where they are — metro vs rural, specific cities | `getCampaignSettings` location targets |
+| Device split | How they search — mobile-heavy suggests on-the-go/urgent need | Infer from ad performance patterns |
+| Time-of-day patterns | When they search — business hours vs evenings vs weekends | `getCampaignPerformance` daily data |
+
+## Persona Template
+
+Use this full template for the persisted JSON file. In the **report output**, personas appear as a compact 3-column table (name, example searches, value). The JSON file has the full detail for downstream skills like `/ads-copy`:
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| **Name** | Descriptive label capturing their defining trait | "The Emergency Caller" |
+| **Demographics** | Role, context, location type | Homeowner, suburban, dual-income household |
+| **Primary goal** | What they're trying to accomplish RIGHT NOW | Fix a burst pipe before it damages the floor |
+| **Pain points** | What's driving them to search | Can't wait for regular business hours. Worried about cost. Doesn't know who to trust |
+| **Search language** | Actual search terms from the data that this persona uses | "emergency plumber near me", "plumber open now", "burst pipe repair cost" |
+| **Decision trigger** | What makes them click the ad and convert | Seeing "24/7" and "Same Day" in the headline. Phone number in the ad. Reviews mentioned |
+| **Value to business** | Estimated revenue or conversion value | High urgency = willing to pay premium. Avg ticket $350-800 |
+
+## Derivation Rules
+
+- Each persona MUST be grounded in actual search term clusters from the data. If you can't point to 5+ search terms that this persona would use, the persona is speculative — drop it
+- If all search terms look the same (single-intent account), identify 1-2 personas max. Don't force 3
+- Name personas by their dominant behavior, not demographics: "The Comparison Shopper" is more useful than "Female 35-44"
+- Include the actual search terms from the data that map to each persona — this directly informs ad copy decisions
+
+## Persist Personas
+
+Save to `{data_dir}/personas/{accountId}.json`:
+
+```json
+{
+ "account_id": "1234567890",
+ "saved_at": "2024-01-15T10:30:00Z",
+ "personas": [
+ {
+ "name": "The Emergency Caller",
+ "demographics": "Homeowner, suburban, any age",
+ "primary_goal": "Fix an urgent problem right now",
+ "pain_points": ["Can't wait", "Worried about cost", "Doesn't know who's reliable"],
+ "search_terms": ["emergency plumber near me", "plumber open now", "burst pipe repair"],
+ "decision_trigger": "24/7 availability, phone number visible, reviews",
+ "value": "High — willing to pay premium for urgency"
+ }
+ ]
+}
+```
+
+These personas feed directly into `/ads-copy` for headline generation and `/ads` for keyword strategy.
diff --git a/google-ads/shared/gaql-cookbook.md b/google-ads/shared/gaql-cookbook.md
index 1b87ad84..a1375367 100644
--- a/google-ads/shared/gaql-cookbook.md
+++ b/google-ads/shared/gaql-cookbook.md
@@ -217,7 +217,9 @@ ORDER BY segments.date DESC
## Specialized queries
-### Zero-conversion high-spend keywords (waste detection)
+### Zero-conversion keywords by spend (waste detection)
+
+Use this query to surface waste candidates. The `/ads-audit` skill's waste formula uses a stricter threshold: `spend > 2x account avg CPA` (not clicks > 10). Calculate account avg CPA from `listCampaigns` data first, then filter these results accordingly.
```
SELECT campaign.name, ad_group.name,
@@ -228,7 +230,6 @@ FROM keyword_view
WHERE segments.date DURING LAST_30_DAYS
AND campaign.status = 'ENABLED'
AND metrics.conversions = 0
- AND metrics.clicks > 10
ORDER BY metrics.cost_micros DESC
LIMIT 50
```