Open-source SEO, GEO, and marketing skills for AI agents.
feat(ads): industry templates, margin-aware math, launch mode, landing page scoring (#39)
Tong Chen287219f90e62
diff --git a/bin/toprank-change-watch b/bin/toprank-change-watchnew file mode 100755index 00000000..32340b1e--- /dev/null+++ b/bin/toprank-change-watch@@ -0,0 +1,129 @@+#!/usr/bin/env bash+# toprank-change-watch — surface pending Google Ads change-impact reviews+#+# Designed to be wired as a Claude Code SessionStart hook:+# {+# "hooks": {+# "SessionStart": [+# { "hooks": [ { "type": "command", "command": "toprank-change-watch" } ] }+# ]+# }+# }+#+# Reads every `{data_dir}/change-log.json` under ~/.toprank/ads/<account>/ and prints+# any change whose `review_after` date has passed and `reviewed: false`. Output is+# piped straight into the Claude session as additional context, so the assistant can+# proactively offer to run the impact review.+#+# Also supports generating an .ics calendar file for a specific change so the user+# gets a cross-platform reminder in their own calendar app:+#+# toprank-change-watch ics <account> <change_id> > reminder.ics+#+# Change log schema (written by /ads when it executes a mutation):+# {+# (see google-ads/ads/references/change-tracking.md for the authoritative schema)+# "changes": [+# {+# "id": "chg_1729872000000",+# "timestamp": "2026-04-14T12:00:00Z",+# "summary": "Paused 3 zombie keywords in Tukwila Search",+# "reviewAfter": "2026-04-21", # 7d for bid/keyword, 14d for structural+# "reviewWindow": "7d",+# "reviewed": false,+# "details": { "campaignName": "Tukwila Search" }+# }+# ]+# }+set -euo pipefail++STATE_DIR="${TOPRANK_STATE_DIR:-$HOME/.toprank}"+ADS_DIR="$STATE_DIR/ads"+TODAY="$(date -u +%Y-%m-%d)"++# Subcommand: ics <account> <change_id>+if [ "${1:-}" = "ics" ]; then+ ACCOUNT="${2:?Usage: toprank-change-watch ics <account> <change_id>}"+ CHANGE_ID="${3:?Usage: toprank-change-watch ics <account> <change_id>}"+ LOG="$ADS_DIR/$ACCOUNT/change-log.json"+ [ -f "$LOG" ] || { echo "No change log for account $ACCOUNT" >&2; exit 1; }++ # Extract review_after + summary for the change using python (always available)+ python3 - "$LOG" "$CHANGE_ID" <<'PY'+import json, sys, datetime, uuid+log_path, change_id = sys.argv[1], sys.argv[2]+with open(log_path) as f:+ data = json.load(f)+change = next((c for c in data.get("changes", []) if c.get("id") == change_id), None)+if not change:+ sys.exit(f"change {change_id} not found")+d = change["reviewAfter"].replace("-", "")+summary = change["summary"].replace("\n", " ")+uid = f"{change_id}-{uuid.uuid4().hex[:8]}@toprank"+now = datetime.datetime.utcnow().strftime("%Y%m%dT%H%M%SZ")+ics = f"""BEGIN:VCALENDAR+VERSION:2.0+PRODID:-//toprank//change-watch//EN+BEGIN:VEVENT+UID:{uid}+DTSTAMP:{now}+DTSTART;VALUE=DATE:{d}+DTEND;VALUE=DATE:{d}+SUMMARY:Review Google Ads change: {summary}+DESCRIPTION:Run /ads-audit to measure impact against baseline.\\nChange ID: {change_id}+BEGIN:VALARM+TRIGGER:-PT9H+ACTION:DISPLAY+DESCRIPTION:Review ads change today+END:VALARM+END:VEVENT+END:VCALENDAR+"""+print(ics)+PY+ exit 0+fi++# Default: scan all accounts and print pending reviews+[ -d "$ADS_DIR" ] || exit 0++pending=0+for log in "$ADS_DIR"/*/change-log.json; do+ [ -f "$log" ] || continue+ account="$(basename "$(dirname "$log")")"+ # Print pending reviews for this account; stream to stdout so SessionStart captures it+ while IFS= read -r line; do+ [ -z "$line" ] && continue+ if [ $pending -eq 0 ]; then+ echo ""+ echo "## Pending Google Ads change-impact reviews"+ echo ""+ echo "The following changes have reached their review window. Offer to run"+ echo "a scoped /ads-audit to measure impact against the baseline captured"+ echo "when each change was made:"+ echo ""+ fi+ pending=1+ echo "- **$account**: $line"+ done < <(python3 - "$log" "$TODAY" <<'PY'+import json, sys+log_path, today = sys.argv[1], sys.argv[2]+try:+ with open(log_path) as f:+ data = json.load(f)+except Exception:+ sys.exit(0)+for c in data.get("changes", []):+ if c.get("reviewed"):+ continue+ review_after = c.get("reviewAfter", "") or c.get("review_after", "")+ if review_after and review_after[:10] <= today:+ cid = c.get("id", "?")+ summary = c.get("summary", "(no summary)")+ camp = (c.get("details") or {}).get("campaignName") or "account-wide"+ print(f"`{cid}` ({camp}) — {summary} — review due {review_after[:10]}")+PY+)+done++exit 0diff --git a/google-ads/ads-audit/SKILL.md b/google-ads/ads-audit/SKILL.mdindex 87b05377..44824475 100644--- a/google-ads/ads-audit/SKILL.md+++ b/google-ads/ads-audit/SKILL.md@@ -46,11 +46,13 @@ Match campaign names, ad group names, and keyword themes using case-insensitive## Reference Documents**Always read before Phase 2:**-- `references/account-health-scoring.md` — Diagnostic thresholds, red flags, interpretation matrices, and benchmark tables+- `references/account-health-scoring.md` — Diagnostic thresholds, red flags, interpretation matrices, pulse metric annotation rules, and the dollar-driven Quick Wins filter+- `../shared/industry-templates.json` — Industry presets (margin, AOV, target CPA, red flags, quick-start negatives). Cache in memory for the session+- `../shared/ppc-math.md` — Break-even CPA, headroom, LTV:CAC, IS opportunity, budget forecasting. Read before computing any dollar-denominated finding**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)+- `references/business-context.md` — Website crawl procedure, business-context.json schema, and unit economics population rules (read during Phase 3)**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@@ -156,12 +158,20 @@ 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).-**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**:+**Launch mode (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. Switch to **Launch mode**:+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+2. Layer 2 (structure check only) — campaign organization, keyword themes, ad copy completeness, industry-template red-flag checks+3. Skip Layers 3-5 — they'd be statistically meaningless. Still compute and persist pulse metrics (with `"low_data": true`) so re-audits have a baseline+4. Report format: use the launch-mode template — no pulse metrics (too little data to compute waste or headroom in dollars), no dollar-impact claims. Instead surface a **Readiness checklist** scored `ready | needs fix | blocker` and a **Next milestone** trigger+5. **Set the next milestone** in `audit-history.json`:+ ```json+ "next_milestone": { "conversions": 30, "spend_usd": 1000, "check_after": "2026-05-14" }+ ```+ The thresholds are `max(30, industry_template.smart_bidding_min_conv_month)` for conversions, `$1,000` for spend, and 30 days out for the date. Whichever hits first triggers the next full audit.+6. Still run Phase 2.5 (personas) and Phase 3 (business context) — these are valuable regardless of data volume. Use `industry_template.recommended_conversion_actions` to recommend missing conversion actions.++**Milestone check on subsequent runs:** If `audit-history.json.next_milestone` exists and any threshold has been crossed, graduate to a full audit and clear the milestone. Otherwise repeat launch-mode with a brief "tracking toward milestone" update.## Phase 2: Analyze@@ -183,7 +193,7 @@ Report passes (organized by action type):**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.-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."+Read `references/account-health-scoring.md` for diagnostic thresholds, red flags, and interpretation matrices. The threshold bands tell you what's "bad enough to flag" vs. "acceptable" — use them to decide whether a finding makes it into the report at all.---@@ -409,9 +419,33 @@ Write to `{data_dir}/business-context.json` using the schema in `references/busi## 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 report uses the **3-pass structure** — organized by what the user should do, not by what dimension was analyzed. Lead with the three pulse metrics (each self-narrating), then the three passes, then Quick Wins, personas, and questions.**The #1 rule: no duplication.** Each finding appears in exactly one place.+**The #2 rule: no artificial ratings.** No letter grades. No emoji verdict labels. No severity buckets. Every finding carries its dollar impact and `time_to_fix`; the pulse metrics carry their top contributor and a pass pointer. That's all the prioritization signal the user needs — and it can't invert on dollars.++### Annotating every finding++Each Pass 1/2/3 finding must carry two fields (and only two):++- `dollar_impact_usd`: the monthly dollar value of the waste / opportunity. Use margin-aware framing when `business-context.json.unit_economics.aov_usd` and `profit_margin` are available (see `../shared/ppc-math.md`); fall back to account-average heuristics otherwise. Never mix framings in one report.+- `time_to_fix`: descriptive only — `<5min` | `<15min` | `<30min` | `<2h` | `>2h`. How long the fix takes, not how important it is.++Findings that can't be dollar-denominated (tracking broken, policy risk, missing consent mode) use `dollar_impact_usd: "blocker"` instead of a number. Blockers always float to the top of their pass and always qualify for Quick Wins regardless of fix time.++Sort findings within each pass by `dollar_impact_usd` descending. Blockers first. No severity label, no priority label — the dollar number IS the priority.++### Annotating the pulse metrics++Each pulse metric line is a self-contained finding. It states the raw number, names the single biggest contributor, and points to the pass that fixes it. Rules in `references/account-health-scoring.md` → "Pulse Metrics — The Only Scoreboard":++1. **Waste** — `$X/mo (Y% of spend) · top: "[keyword/term/campaign]" $Z/mo · → Pass 1`+ Signal override: if conversion tracking is broken, replace `$X/mo (Y%)` with `⚠️ Cannot compute — conversion tracking broken` and point to the tracking fix.+2. **Demand captured** — `X% · top opportunity: "[campaign]" ~$Y/mo headroom · → Pass 2`+ Relevance override: if rank-lost IS > 30% on a campaign, point to Pass 3 and explicitly say "fix relevance first — more budget won't help."+3. **CPA** — `$X · vs [industry $Y–$Z OR break-even $Y] · [trend or top structural driver] · → Pass 3 or "healthy — no action"`++**On re-audits**, diff each metric line against the previous `audit-history.json` entry and append `_(was $Y/mo — [what changed])_` when the delta is >5%. When the delta is <5%, say `_(unchanged)_`. No bucket-flipping, no emoji verdict swaps — just three numbers moving (or not).### Pulse Metrics@@ -436,22 +470,41 @@ After each audit, append a snapshot to `{data_dir}/audit-history.json`:"date": "2026-04-11","date_range": "2026-03-12 to 2026-04-11","account_id": "7521406707",- "total_spend": 1431.48,+ "mode": "full",+ "total_spend": 14320.00,"total_conversions": 72,"metrics": {- "waste_rate": 11.3,- "demand_captured": 42.7,- "cpa": 19.88+ "waste": {+ "usd_per_month": 1240,+ "pct_of_spend": 8.7,+ "top_contributor": "keyword 'free dog food' — $340/mo",+ "tracking_blocker": false+ },+ "demand_captured": {+ "pct": 42.7,+ "top_opportunity": "Tukwila Search — ~$2,100/mo headroom at 35% budget-lost IS",+ "rank_lost_blocker": false+ },+ "cpa": {+ "usd": 19.88,+ "benchmark_low": 25,+ "benchmark_high": 65,+ "break_even": 72,+ "trend_vs_last": -2.14+ }},"top_actions": ["Paused 'free dog food' keyword ($120 waste)","Budget-lost IS 40% on Tukwila Search at $14 CPA"- ]+ ],+ "next_milestone": null}]}```+For launch-mode audits, set `"mode": "launch"`, mark each metric with `"low_data": true`, and populate `next_milestone` with the conversion/spend/date thresholds that graduate the next audit to full mode.+**On first audit:** Create the file. Show raw values with no comparison.**On subsequent audits:** Load the previous entry and compute trends:@@ -463,29 +516,52 @@ After each audit, append a snapshot to `{data_dir}/audit-history.json`:```# [Business Name] — Ads Audit-**[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]+[Date range] · $X,XXX spent · XX conversions · Last 30 days[If scoped] Scoped to: [description]+[If unit_economics.source == "inferred_from_template"]+_Profitability estimates use industry defaults — confirm your actual AOV and margin for sharper recommendations._++**Waste: $X/mo (Y% of spend)** — top: "[keyword/term/campaign]" $Z/mo · → Pass 1+[if re-audit] _(was $A/mo — [what changed])_ or _(unchanged)_++**Demand captured: X%** — top opportunity: "[campaign]" ~$Y/mo headroom · → Pass 2+[if rank-lost IS > 30% on a campaign: "Rank-lost IS X% on [campaign] — fix relevance first, more budget won't help · → Pass 3"]+[if re-audit] _(was Y% — [what changed])_ or _(unchanged)_++**CPA: $X** — vs [industry $Y–$Z OR break-even $Y] · [trend or top driver] · → Pass 3 or "healthy — no action"+[if re-audit] _(was $Y — [what changed])_ or _(unchanged)_-[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.]+[If conversion tracking is broken, the Waste line is replaced with:]+**Waste: ⚠️ Cannot compute — conversion tracking broken** · → Pass 1 (fix tracking first)## Stop Wasting (Pass 1)-1. **[Action]** — saves $X/month-2. **[Action]** — saves $X/month-3. **[Action]** — saves $X/month+1. **[Action]** — saves $X/mo · `<15min`+2. **[Action]** — saves $X/mo · `<30min`+3. **[Action]** — saves $X/mo · `<2h`## 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+1. **[Action]** — est. +$X/mo revenue (+Y conv at $Z CPA) · `<30min`+2. **[Action]** — est. +$X/mo · `<2h`+3. **[Action]** — est. +$X/mo · `<2h`## Fix Fundamentals (Pass 3)-1. **[Action]** — est. X% CPC reduction on $Y/month spend-2. **[Action]** — [impact]-3. **[Action]** — [impact]+1. **[Action]** — est. $X/mo CPC savings on $Y/mo spend · `>2h`+2. **[Action]** — [impact in $/mo] · `<2h`+3. **[Action]** — [impact in $/mo] · `<30min`++Findings are sorted by dollar impact within each pass. Blockers (tracking,+policy, consent) appear at the top of their pass regardless of dollar value+because they unblock measurement.++## Quick Wins+[Auto-generated: findings where dollar_impact_usd >= 200 AND+time_to_fix IN ('<5min','<15min'), sorted by $ impact desc, max 5.+Blockers (tracking/policy fixes) are pinned at the top regardless of+dollar figure. Each item must include the exact /ads command where+applicable. If none qualify, omit this section entirely — don't fabricate.]++1. [Action] — saves ~$X/mo (`<5min`) · `/ads [command]`+2. [Action] — saves ~$X/mo (`<15min`) · `/ads [command]`Run `/ads` to execute any of these.@@ -501,6 +577,38 @@ Run `/ads` to execute any of these.Max 2-3 questions. Don't ask what you can infer from the data.]```+**Launch-mode report variant** (total spend < $500 OR total conversions < 10):++```+# [Business Name] — Ads Launch Check+**Launch mode** · [Date range] · $XXX spent · X conversions+_Too little data to compute waste or headroom in dollars — come back after the milestone below._+[If scoped] Scoped to: [description]++[2-3 sentences describing setup quality and readiness — what's configured,+what's missing, what should happen before the next milestone. No optimization+claims, no dollar impact, no score.]++## Readiness Checklist+- ✅ / ⚠️ / 🚫 Conversion tracking — [what's set up or missing]+- ✅ / ⚠️ / 🚫 Campaign structure — [organization quality]+- ✅ / ⚠️ / 🚫 Ad copy completeness — [RSA count, asset coverage]+- ✅ / ⚠️ / 🚫 Targeting — [geo, network, language]+- ✅ / ⚠️ / 🚫 Industry red flags — [from industry-templates.json]++## Fix Before Next Milestone+1. [Blocker or needs-fix item] — `/ads` command or manual step+2. ...++## Next Milestone+Come back for a full audit when **any** of these hits:+- 📈 **XX conversions** (currently X)+- 💵 **$X,000 spent** (currently $XXX)+- 📅 **[date 30 days out]**++I'll remember the milestone — next `/ads-audit` run will auto-upgrade to a full audit.+```+### What makes a good action item- **Specific:** "Pause keyword 'free dog food' — $847 spent, 0 conversions" not "Review underperforming keywords"@@ -528,7 +636,8 @@ After the report, add ONE handoff based on the biggest issue found:| 3+ converting search terms not yet keywords | Offer to add them 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 |+| High CTR but low conversion rate | Suggest `/ads-landing` to score the landing page |+| Any ad group with CTR > account avg AND CVR < 50% of account avg | Suggest `/ads-landing` for that landing page |Don't list all possible handoffs — pick the one that matches the #1 action item.diff --git a/google-ads/ads-audit/references/account-health-scoring.md b/google-ads/ads-audit/references/account-health-scoring.mdindex 5bf6630b..7beabffb 100644--- a/google-ads/ads-audit/references/account-health-scoring.md+++ b/google-ads/ads-audit/references/account-health-scoring.md@@ -214,15 +214,110 @@ Always report: "Overall CPA is $X, but brand CPA is $Y and non-brand CPA is $Z."----## Pulse Metrics — What to Track+## Pulse Metrics — The Only Scoreboard-Instead of a composite score, the audit tracks 3 objective metrics:+No letter grades. No emoji verdicts. No rating buckets. The audit surfaces **3 pulse metrics**, each annotated with its biggest contributor and a pointer to the pass that fixes it. The metric IS the verdict — read it as dollars and act on it directly.-| 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 |+Every pulse metric must answer three questions inline:+1. **What's the number?** (raw value)+2. **What's driving it?** (the single biggest contributor, named)+3. **Where do I fix it?** (pointer to Pass 1/2/3)++### The three metrics++| Metric | What it measures | Better = | How to compute |+|---|---|---|---|+| **Waste** | $/mo burning on zero-conversion spend | Lower | `Wasted Spend Calculation` section below, extrapolated to 30 days |+| **Demand captured** | % of eligible impressions won on profitable campaigns | Higher | Weighted avg `search_impression_share` across campaigns with ≥1 conversion, weighted by spend. If `unit_economics` exists, use `CPA ≤ Break-Even CPA` as the profitability filter instead |+| **CPA** | Cost per conversion | Lower or stable | `total spend / total conversions` — compare to industry benchmarks below or to `unit_economics.break_even_cpa` if available |++### Annotation rules (what each metric line must include)++**Waste line:**+- Dollar value extrapolated to 30 days: `$X/mo (Y% of spend)`+- Top single contributor: keyword / search term / campaign name + its dollar impact+- Pointer: `→ Pass 1`+- **Signal failure override:** If conversion tracking is broken (no conversion actions, or 0 conversions with 50+ clicks), replace the dollar figure with `⚠️ Cannot compute — conversion tracking broken` and point to the tracking fix. Waste is meaningless when you can't measure conversions.++**Demand captured line:**+- Percentage: `X%`+- Top single opportunity: campaign name + headroom in $/mo (margin-aware where possible)+- Pointer: `→ Pass 2`+- **Relevance override:** If rank-lost IS > 30% on any campaign, name that campaign and flag that more budget won't help — "fix relevance first" — and point to Pass 3 instead.++**CPA line:**+- Dollar value: `$X`+- Context: either "vs industry $Y–$Z" (from `industry-templates.json`) or "vs break-even $Y" (from `unit_economics`)+- Top single structural driver (if CPA is unhealthy): which campaign is pulling it up, or which QS component is below average+- Pointer: `→ Pass 3` (structural fixes) or "healthy — no action" if CPA is stable and within benchmark++### Quick Wins section (auto-generated, dollar-driven)++After the 3-pass report, emit a `## Quick Wins` section containing every finding where:++```+dollar_impact_usd >= 200 AND time_to_fix IN ('<5min', '<15min')+```++Plus any **signal/tracking/policy fix** regardless of dollar value — these qualify unconditionally because they unblock measurement.++Sort by dollar impact descending (signal fixes pinned to the top). Max 5 items. If none qualify, omit the section entirely — don't fabricate.++Every Quick Win must be executable via a single `/ads` command where applicable and include the command text. Examples:+- `Add 7 negatives to Tukwila Search — saves ~$340/mo (<5 min) · /ads add negatives to Tukwila Search: jobs, careers, salary, diy, free, reddit, training`+- `Enable Enhanced Conversions — unblocks measurement (<15 min) · Configure in Google Ads UI (not /ads)`++### `time_to_fix` field (kept — descriptive, not a rating)++Every finding carries one descriptive field: `time_to_fix` ∈ `<5min | <15min | <30min | <2h | >2h`. This is how long the fix takes, not how important it is. It's used only as a filter input for Quick Wins. There is no severity tag, no priority label, no letter — the dollar figure on each finding carries all the priority information the user needs. Sort and filter on dollars.++### What goes in `audit-history.json`++Persist the pulse metrics with their top contributors. No verdict, no grade, no severity counts.++```json+{+ "date": "2026-04-14",+ "date_range": "2026-03-15 to 2026-04-14",+ "account_id": "7521406707",+ "mode": "full",+ "total_spend": 14320.00,+ "total_conversions": 72,+ "metrics": {+ "waste": {+ "usd_per_month": 1240,+ "pct_of_spend": 8.7,+ "top_contributor": "keyword 'free dog food' — $340/mo",+ "tracking_blocker": false+ },+ "demand_captured": {+ "pct": 42.7,+ "top_opportunity": "Tukwila Search — ~$2,100/mo headroom at 35% budget-lost IS",+ "rank_lost_blocker": false+ },+ "cpa": {+ "usd": 19.88,+ "benchmark_low": 25,+ "benchmark_high": 65,+ "break_even": 72,+ "trend_vs_last": -2.14+ }+ },+ "top_actions": [+ "Paused 'free dog food' keyword ($120 waste)",+ "Budget-lost IS 40% on Tukwila Search at $14 CPA"+ ],+ "next_milestone": null+}+```++On re-audits, diff the three metric lines directly — no abstract bucket movement:++- `Waste: $640/mo (4.1%) _(was $1,240/mo — 3 fixes applied)_`+- `Demand captured: 58% _(was 42% — Tukwila budget increased)_`+- `CPA: $18.40 _(was $19.88 — stable)_`++Three numbers, three deltas, zero artificial ratings. If a number didn't move, say "unchanged." If it moved the wrong way, show the delta without sugar-coating.---diff --git a/google-ads/ads-audit/references/business-context.md b/google-ads/ads-audit/references/business-context.mdindex 67b4befc..61166d53 100644--- a/google-ads/ads-audit/references/business-context.md+++ b/google-ads/ads-audit/references/business-context.md@@ -58,6 +58,7 @@ Write the complete business context to `{data_dir}/business-context.json`:{"business_name": "","industry": "",+ "industry_template_key": "","website": "","services": [],"locations": [],@@ -79,6 +80,14 @@ Write the complete business context to `{data_dir}/business-context.json`:"competitive_terms": [],"long_tail_opportunities": []},+ "unit_economics": {+ "aov_usd": null,+ "profit_margin": null,+ "ltv_usd": null,+ "avg_customer_lifespan_months": null,+ "source": "user_provided | inferred_from_template | unknown",+ "last_confirmed": ""+ },"social_proof": [],"offers_or_promotions": [],"landing_pages": {},@@ -89,3 +98,19 @@ Write the complete business context to `{data_dir}/business-context.json`:```Include `audit_date` (today's date) and `account_id` so future skills know when this was last refreshed.++## Unit Economics — How to Populate++Unit economics drive margin-aware profitability framing (see `../../shared/ppc-math.md`). Three ways to populate, in priority order:++1. **User-provided (strongest):** During Phase 3 intake, ask: "What's your average order value and rough profit margin?" Set `source: "user_provided"` and stamp `last_confirmed` with today's date.++2. **Inferred from industry template (fallback):** If the user doesn't know, read `../../shared/industry-templates.json` and copy `typical_margin` + the midpoint of `aov_range_usd`. Set `source: "inferred_from_template"`. Flag prominently in the audit: "_Profitability estimates use industry defaults — confirm your actual AOV and margin for sharper recommendations._"++3. **Leave null (last resort):** If no industry template match and user declines to provide, leave all fields `null`. The audit falls back to account-average heuristics and skips break-even / headroom framing.++**Never compute break-even CPA when `source == "inferred_from_template"` without surfacing the assumption.** A template-inferred margin that's off by 15% changes every Pass 1 dollar impact. Transparency is non-negotiable.++### Industry template matching++During Phase 3, after resolving `industry`, also set `industry_template_key` by matching against `templates.*.aliases` in `industry-templates.json` (case-insensitive substring). If no match, use `"generic"`. This key is the stable handle downstream skills use — industry names drift across audits, the key doesn't.diff --git a/google-ads/ads-landing/SKILL.md b/google-ads/ads-landing/SKILL.mdnew file mode 100644index 00000000..0d560281--- /dev/null+++ b/google-ads/ads-landing/SKILL.md@@ -0,0 +1,166 @@+---+name: ads-landing+description: Score and diagnose Google Ads landing pages. Use when asked to audit a landing page, check landing page quality, diagnose high-CTR but low-conversion-rate ad groups, improve Quality Score's Landing Page Experience component, or compare an ad group's messaging against its landing page. Trigger on "landing page audit", "landing page score", "landing page quality", "why is my conversion rate low", "LPX", "landing page experience", "ad to page match", or when `/ads-audit` surfaces a high-CTR / low-CVR ad group.+argument-hint: "<landing page URL or ad group name>"+---++## Setup++Read and follow `../shared/preamble.md` — it handles MCP detection, token, and account selection. If config is already cached, this is instant.++# Landing Page Scoring + Diagnostic++Google Ads campaigns fail on the landing page more often than in the auction. A great RSA that sends traffic to a slow, unfocused, or mismatched page burns budget twice — once on the click, once on the lost conversion. This skill scores landing pages on **5 weighted dimensions** and emits concrete fixes.++## When to run this++| Trigger | Source |+|---------|--------|+| User explicitly asks for a landing page audit | Direct invocation |+| `/ads-audit` Layer 4 finds ad groups with CTR > account avg AND CVR < 50% of account avg | Auto-handoff |+| Quality Score diagnosis flags "Landing Page Experience: Below Average" on high-spend keywords | `/ads` routes here |+| `/ads-copy` is about to write copy for a page the user hasn't validated | Preflight check |++Only score pages that actually run ad traffic. Don't score random marketing pages.++## Reference Documents++- `references/scoring-rubric.md` — The 5-dimension weighted rubric, thresholds, and evidence fields (read this before running any score)+- `../ads-audit/references/business-context.md` — Uses `{data_dir}/business-context.json` for brand voice and differentiators to check message match+- `../ads/references/quality-score-framework.md` — Read only if the user's goal is QS improvement specifically++## Phase 1: Resolve the target pages++Figure out which URLs to score. In priority order:++1. **User supplied a URL** — score that one page, skip discovery.+2. **User supplied an ad group or campaign name** — pull `listAds` for that ad group and extract unique final URLs. Normalize (strip tracking params, preserve path + query that affects routing).+3. **Auto-handoff from `/ads-audit`** — the handoff passes the specific ad groups flagged in Layer 4. Pull their final URLs.+4. **No arguments** — pull `listAds` for the whole account, rank final URLs by spend (last 30 days), and propose the top 3 to score. Ask the user to confirm.++**De-duplicate aggressively.** Many ads point to the same final URL — score each unique URL once, then map back to all the ad groups that use it.++## Phase 2: Gather signal (parallel)++Run all of these in a single tool-use turn:++1. **WebFetch the landing page** — capture visible headline, subheadline, primary CTA text, form fields, trust signals, body copy tone. Also capture the full HTML so we can spot script bloat and above-the-fold content.+2. **PageSpeed Insights API call** — use `https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url={url}&strategy=mobile&category=performance&category=accessibility&category=best-practices&category=seo` via WebFetch. No API key needed for single-URL queries. Extract LCP, CLS, INP, TTI, performance score, and the top 3 opportunities (`lighthouseResult.audits`).+3. **Pull the referring ad copy** — from the ad group(s) that send traffic here, get headlines and descriptions via `listAds`. This is the message-match baseline.+4. **Read `{data_dir}/business-context.json`** — for brand voice, differentiators, offers, target audience. If it's missing, point the user to `/ads-audit` first. Don't guess the business.+5. **Pull conversion data** for the ad group(s) — `listAds` + search term report for the ad groups pointing here. Used to calculate CVR and to ground dollar-impact estimates.++If any single call fails, continue — note the gap in the report rather than blocking. PageSpeed Insights can rate-limit; if it does, fall back to manual timing annotation ("PSI unavailable — could not score Page Speed") and deflate the final grade's confidence rather than skipping the dimension.++## Phase 3: Score the page++Read `references/scoring-rubric.md` and score each dimension 0-100 with evidence. The dimension scores are real measurements (PageSpeed Insights numbers, word-for-word copy comparison, form field counts, etc.) — they're not artificial ratings, they're observations.++Compute the weighted composite only as an **internal reference number** for the dollar-lift formula below. Do not surface it as a letter grade. The user sees the dimension-level measurements and the estimated dollar lift — the composite is plumbing.++```+internal_composite = 0.25 * Message Match+ + 0.25 * Page Speed+ + 0.20 * Mobile Experience+ + 0.15 * Trust Signals+ + 0.15 * Form & CTA+```++**Dollar lift is the headline.** If `business-context.json.unit_economics` has `aov_usd` + `profit_margin`, compute the estimated monthly lift from raising the composite by 15 points (see `../shared/ppc-math.md`):++```+Target lift = min(+15, 90 - internal_composite) # cap at 90 internal+Assumed CVR lift = target_lift / 100 * 0.5 # cap at 50% relative lift+Current conversions = ad group conversions from last 30d+Additional conversions = current_conversions * assumed_CVR_lift+Additional revenue = additional_conversions * AOV+Additional profit = additional_conversions * AOV * profit_margin+```++Present the lift as `fixing this page is worth ~$X/mo in profit` — never as a guarantee. The 50% cap on CVR lift and the 15-point cap on score improvement keep estimates out of fantasy territory. If `unit_economics` isn't available, skip the dollar line entirely rather than making up a number — the dimension measurements still stand on their own.++## Phase 4: Deliver the report++Max 60 lines. Lead with the dollar lift (when available) and the single biggest fix. No letter grade.++```+# Landing Page — [URL]+Ads sending traffic here: [N ad groups] · [X clicks/mo] · [$Y spent/mo] · CVR [Z%]+[If unit_economics available] **Estimated lift from top 3 fixes: ~$X/mo in profit**+[If unit_economics is missing] _(Dollar lift unavailable — no verified AOV/margin. Confirm unit economics in business-context.json for sharper estimates.)_++**Biggest leak:** [one sentence naming the dimension and the specific observation, e.g. "LCP is 5.8s on mobile — 2.8s slower than the 3s threshold that kills conversion rate."]++## Measurements+| Dimension | Measurement | Top Finding |+|-----------|-------------|-------------|+| Message Match | [word-for-word verdict: Match / Drift / Broken] | [one line citing ad H1 vs page H1] |+| Page Speed | LCP Xs · INP Xms · CLS X · PSI perf score X | [top blocking audit from Lighthouse] |+| Mobile Experience | PSI accessibility X · [mobile-specific issue count] | [one line: e.g. "No click-to-call, form below fold"] |+| Trust Signals | [review count, years in business, cert count] | [one line: e.g. "Zero named testimonials, copyright 2023"] |+| Form & CTA | [field count] fields · CTA text: "[button]" · [above/below fold] | [one line: e.g. "11 fields for a free quote"] |++## Fix First (top 3, ranked by estimated $ lift)+1. **[Action]** — est. +$X/mo · `<time_to_fix>`+ Evidence: [the actual text/number from the page or PSI audit]+2. **[Action]** — est. +$X/mo · `<time_to_fix>`+ Evidence: [...]+3. **[Action]** — est. +$X/mo · `<time_to_fix>`+ Evidence: [...]++## Message Match Detail+Ad headline: "[actual headline from top-spending ad]"+Page H1: "[actual H1 from landing page]"+Observation: [Match / Drift / Broken] — [one-line rationale citing the specific words that match or don't]++## Handoff+[Pick one:]+- Page speed dominates the problem → "Share these fixes with your developer: [list]"+- Message mismatch dominates → "Run /ads-copy to rewrite ads to match the page, or update the page to match the ads"+- Form friction dominates → "Reduce form to [specific fields]. Every removed field is ~10% more conversions"+```++## Writing back to history++Append the score to `{data_dir}/landing-page-history.json` so re-audits can show deltas:++```json+{+ "pages": {+ "https://example.com/services/roofing": {+ "history": [+ {+ "date": "2026-04-14",+ "internal_composite": 67,+ "dimensions": {+ "message_match": 72,+ "page_speed": 45,+ "mobile": 80,+ "trust": 70,+ "form_cta": 65+ },+ "psi_mobile_lcp_s": 4.2,+ "psi_mobile_cls": 0.15,+ "psi_mobile_inp_ms": 320,+ "estimated_lift_usd_per_month": 380,+ "ad_groups": ["Tukwila Search - Roofing"],+ "monthly_spend": 1240.50,+ "monthly_cvr": 2.1,+ "biggest_leak": "Page Speed — LCP 4.2s on mobile"+ }+ ]+ }+ }+}+```++`internal_composite` is stored for trend tracking only — it's the internal reference number used by the dollar-lift formula, never shown to the user as a letter grade. On subsequent runs against the same URL, diff the raw dimension measurements and the dollar lift: `LCP 4.2s → 2.1s · Page Speed 45 → 78 · estimated lift $380/mo → $120/mo remaining`. Three measurements moved, no artificial grade flip.++## Rules++1. **Never score a page without WebFetch'ing it.** The rubric demands evidence. No WebFetch = no score. Ask the user to help if the page is gated or requires auth.+2. **Never report a PSI number you didn't measure.** If PSI failed, say "PSI unavailable" — don't estimate.+3. **One page at a time unless the user asks for multiple.** Scoring three pages in one turn creates unreadable reports. Batch only when explicitly requested.+4. **Don't rewrite copy here.** This skill diagnoses the page. Handoff to `/ads-copy` for new headlines or `/ads` for bid/negative/budget moves.+5. **Margin-aware dollar impact requires verified unit economics.** If `unit_economics.source == "inferred_from_template"`, append `_(using industry defaults — confirm your AOV/margin for sharper estimates)_` to the lift line.+6. **Always persist.** Every scored page goes into `landing-page-history.json`, even if the user doesn't ask — future audits depend on the baseline.diff --git a/google-ads/ads-landing/references/scoring-rubric.md b/google-ads/ads-landing/references/scoring-rubric.mdnew file mode 100644index 00000000..ddcc71f5--- /dev/null+++ b/google-ads/ads-landing/references/scoring-rubric.md@@ -0,0 +1,203 @@+# Landing Page Measurement Rubric++Five dimensions, each measured against real evidence. The dimension scores are observations (real PageSpeed Insights numbers, word-for-word ad-to-page comparison, form field counts) — not artificial ratings.++There is no letter grade. The report surfaces each dimension's measurement and the top finding, plus a dollar-denominated lift estimate. Internally, the skill computes a weighted composite only to feed the lift formula:++```+internal_composite = 0.25 × Message Match+ + 0.25 × Page Speed+ + 0.20 × Mobile Experience+ + 0.15 × Trust Signals+ + 0.15 × Form & CTA+```++The two 25% dimensions (Message Match, Page Speed) are deliberately weighted equally — Google's Landing Page Experience QS component considers both, and real-world CVR correlates strongly with both. Everything else is secondary. The 0-100 scores per dimension are kept as internal numbers for history tracking and the lift formula; the user-facing report cites the underlying measurement (LCP seconds, field count, H1 word match) rather than the score.++---++## 1. Message Match (25%)++*"Did the user arrive where they expected?"*++The ad promises something. The page must deliver it within 3 seconds of scroll-free viewing. This is the single strongest predictor of CVR lift.++### Scoring++| Score | Rubric |+|-------|--------|+| 90-100 | Page H1 contains the ad's promise word-for-word or a tight synonym. Subhead reinforces. CTA matches the ad's action verb. Offer in ad (if any) is front-and-center on the page |+| 75-89 | H1 clearly relates to the ad's service and location. Primary CTA matches ad intent. Minor drift in tone or offer language |+| 60-74 | Page is on-topic but generic — H1 says "Quality Roofing Services" when the ad said "Emergency Roof Repair in Tukwila". User has to infer the connection |+| 45-59 | Page is about the business but not about the ad's specific angle. Ad pushed urgency, page is evergreen. Ad pushed a specific service, page is a services overview |+| <45 | Homepage, category page, or completely mismatched content. Ad said "free quote", page has no quote CTA. Ad said "24/7", page shows business hours |++### Evidence to capture++- **Ad headline 1** (the one most users see) vs. **Page H1** — quote both verbatim in the report+- **Ad CTA verb** (Get, Book, Call, Shop) vs. **Primary page button text**+- **Offer in ad** (if any) vs. **offer visible above the fold**+- **Location from ad** (if geo-targeted) vs. **location shown on page**+- **Keyword from search query** (pull top search term for the ad group) — does it appear on the page at all?++### Common failure patterns++| Pattern | Fix |+|---------|-----|+| Ad points to homepage | Build a service-specific landing page or change final URL |+| Ad headline promises a discount, page has no mention | Either remove the discount from ad or add it to page hero |+| Ad pushes one service, page lists 15 | Send traffic to a single-service page |+| Ad says "free estimate", page says "call for pricing" | Align the CTA or expand the pricing page |++---++## 2. Page Speed (25%)++*"Can the user even see the page before bouncing?"*++Measured via PageSpeed Insights API on mobile (Google's default crawl profile for ads since 2019). Desktop is secondary.++### Scoring (based on mobile Core Web Vitals)++| Score | LCP | INP | CLS | Notes |+|-------|-----|-----|-----|-------|+| 90-100 | <2.0s | <100ms | <0.05 | All three in green. Page feels instant |+| 75-89 | 2.0-2.5s | 100-200ms | 0.05-0.10 | Mostly green, one metric in yellow |+| 60-74 | 2.5-4.0s | 200-500ms | 0.10-0.25 | All yellow, or one metric in red |+| 45-59 | 4.0-6.0s | 500-1000ms | 0.25-0.40 | Two metrics in red |+| <45 | >6.0s | >1000ms | >0.40 | All three red. User bounced before LCP fired |++If PSI returns a performance score directly, use that as a tiebreaker within the band the vitals place you in.++### Evidence to capture++- LCP (s), INP (ms), CLS (unitless), Performance Score (0-100) — all from mobile strategy+- Top 3 `lighthouseResult.audits` with `score < 0.5` and `details.overallSavingsMs > 200` — these are the biggest levers+- Total page weight (kB), number of blocking scripts, number of image requests++### Common failure patterns++| Audit | Typical fix |+|-------|------------|+| `uses-optimized-images` | Serve WebP/AVIF, compress hero image |+| `render-blocking-resources` | Defer or async third-party scripts (analytics, chat widgets, tag managers) |+| `unused-javascript` | Remove marketing tags that aren't being read (Facebook Pixel on a B2B page, etc.) |+| `largest-contentful-paint-element` points to a hero image | Preload the hero image, set explicit dimensions to prevent CLS |+| `uses-long-cache-ttl` | Configure CDN cache headers |++---++## 3. Mobile Experience (20%)++*"Does the page work with a thumb?"*++70%+ of Google Ads traffic is mobile. A page that renders but is unusable on a 375px viewport is worse than a slow page — users rage-quit.++### Scoring++| Score | Rubric |+|-------|--------|+| 90-100 | Tap targets >48px. Text >=16px body. Sticky CTA or phone number in mobile viewport. Form fits without horizontal scroll. No popups that cover content. PSI accessibility >95 |+| 75-89 | Tap targets adequate, text readable. One minor issue (e.g., hero text partially cropped, footer form below fold) |+| 60-74 | 2+ mobile issues: small tap targets, zoomed-out default viewport, form requires zoom to complete, CTA below fold |+| 45-59 | Unusable without pinch-zoom. Content overflows. Multiple popups. PSI accessibility <75 |+| <45 | Desktop-only site. No mobile viewport meta. Broken rendering |++### Evidence to capture++- `viewport` meta tag present and correct (`width=device-width, initial-scale=1`)+- PSI mobile accessibility score+- Visible above-the-fold content on mobile (from WebFetch rendered markup)+- Presence of click-to-call link (`tel:` anchor) — critical for service businesses+- Presence of sticky mobile CTA+- Popup/interstitial detection — any element with `position: fixed` and `z-index > 1000` covering content++### Common failure patterns++| Pattern | Fix |+|---------|-----|+| Phone number not click-to-call | Wrap in `<a href="tel:...">` |+| No sticky mobile CTA | Add bottom-fixed button bar with primary action |+| Hero image dominates viewport, pushes headline below fold | Reduce hero size, move headline up |+| Popup appears on load | Delay to 30s scroll or remove entirely on paid-traffic pages |++---++## 4. Trust Signals (15%)++*"Would a stranger give this page their credit card or phone number?"*++Trust is the invisible conversion tax. Even a perfect ad-to-page match with blazing speed will lose conversions if the page feels sketchy.++### Scoring++| Score | Rubric |+|-------|--------|+| 90-100 | All of: real reviews/testimonials with names, star rating visible, trust badges (BBB, industry certs), years in business, physical address, phone number, photos of real people/work |+| 75-89 | Most of the above. One category missing (e.g., no certs but strong reviews) |+| 60-74 | Generic trust signals only: stock-photo testimonials, no names, no specifics |+| 45-59 | No reviews, no address, no photos. Just marketing copy |+| <45 | Active distrust signals: broken links, copyright year 3 years old, typos, contact form only (no phone) |++### Evidence to capture++- Review count and star rating (visible on page)+- Named testimonials (first name + last initial minimum)+- Physical address+- Phone number (ideally click-to-call)+- HTTPS + valid certificate+- Copyright year — must be current or last year+- Privacy policy link (critical for lead-gen compliance)++### Common failure patterns++| Pattern | Fix |+|---------|-----|+| No reviews on page | Pull from `business-context.json.social_proof` and add a reviews section |+| Copyright 2023 in 2026 | Update footer — tiny fix, surprisingly high impact on trust perception |+| No phone number on a service page | Add one, use click-to-call |+| Stock photos of "our team" | Replace with real photos, even phone-quality beats stock |++---++## 5. Form & CTA (15%)++*"Can the user actually convert?"*++The page can be perfect, but if the form has 11 fields or the button says "Submit", conversions leak out here.++### Scoring++| Score | Rubric |+|-------|--------|+| 90-100 | Primary CTA above fold, action-oriented ("Get My Free Quote", not "Submit"). Form has 3-4 fields max for lead gen. Clear value prop next to form ("We'll respond within 24h"). No dark patterns |+| 75-89 | CTA visible, form reasonable (5-6 fields), button copy active. One friction point |+| 60-74 | CTA below fold OR form has 7-8 fields OR button is generic ("Submit", "Send") |+| 45-59 | Multiple friction: 9+ field form, generic CTA, no value prop near form, unclear what happens after submit |+| <45 | No clear CTA, form broken, or form requires login/account creation before conversion |++### Evidence to capture++- Number of form fields (required vs. optional)+- Button text verbatim+- Above-fold CTA presence (from WebFetch'd markup, estimate using viewport-sized window)+- Secondary CTAs that might compete with the primary (too many CTAs = analysis paralysis)+- Trust reinforcement next to form (privacy note, response time, guarantee)++### Common failure patterns++| Pattern | Fix |+|---------|-----|+| Form has 10 fields for a "free estimate" | Reduce to name, phone, service type — everything else can wait for the follow-up call |+| Button says "Submit" or "Send" | Change to the action ("Get My Free Quote", "Book My Consultation") |+| Primary CTA below fold | Move above fold or add a sticky header CTA |+| Phone number hidden in footer | Put it in the header AND next to the form |++---++## Calibration notes++- **Don't over-weight speed for non-e-commerce.** A lead-gen page with LCP 3.5s and message-match 95 will convert better than LCP 1.5s with message-match 60. The weighted formula handles this correctly — don't override it.+- **Mobile accessibility floors the grade.** If PSI mobile accessibility < 60, cap Mobile Experience at 59 regardless of other factors. Broken accessibility is a trust/legal issue.+- **Don't trust average CVR as a benchmark without context.** A legal services page at 2% CVR is healthy; an e-commerce page at 2% CVR is broken. Use `industry-templates.json` → `typical_cvr` as the baseline.+- **Confidence decays with missing data.** If PSI didn't run, cap the final score at 85 (can't grade A without speed data). If `business-context.json` is missing, cap Message Match at 80 (can't validate brand voice).diff --git a/google-ads/ads/references/analysis-heuristics.md b/google-ads/ads/references/analysis-heuristics.mdindex 4255ef7d..54ba8a90 100644--- a/google-ads/ads/references/analysis-heuristics.md+++ b/google-ads/ads/references/analysis-heuristics.md@@ -2,6 +2,23 @@Quick-decision thresholds for Google Ads analysis. Use these for fast triage, then read the linked deep-dive reference when you need full diagnostic workflows.+## Framing Priority: Margin-Aware First, Account-Average Second++Before running any heuristic below, check `{data_dir}/business-context.json.unit_economics`. Two branches:++**Branch A — Margin-aware (preferred).** If `aov_usd` and `profit_margin` exist (regardless of source), read `../../shared/ppc-math.md` and use break-even-based thresholds:+- Waste = spend on keywords/terms with `CPA > Break-Even CPA` (where Break-Even CPA = AOV × margin)+- Scaling = campaigns with positive Headroom $ AND Budget-Lost IS > 20%+- Every finding expresses dollar impact as "saves $X/mo" or "captures $X/mo headroom" — not "CPA above average"++If `unit_economics.source == "inferred_from_template"`, append this disclaimer beneath the report header: `_Profitability estimates use industry defaults — confirm your actual AOV and margin for sharper recommendations._`++**Branch B — Account-average (fallback).** If `unit_economics` is null or `aov_usd` is missing, use the account-average heuristics in the tables below. Never mix the two branches in one report — pick one framing and stay consistent.++## Industry Template Calibration++Read `../../shared/industry-templates.json` once per audit (cache in memory). Use `business-context.json.industry_template_key` to select the template. Every threshold marked `[template]` below reads from the template first; the listed value is the fallback if no template match.+## Keyword Classification (mandatory first step)Before evaluating any keyword's performance, classify it by business relevance. This prevents pausing a core business keyword during a short run of poor metrics.diff --git a/google-ads/ads/references/change-tracking.md b/google-ads/ads/references/change-tracking.mdindex 2d619fea..1cae2707 100644--- a/google-ads/ads/references/change-tracking.md+++ b/google-ads/ads/references/change-tracking.md@@ -37,3 +37,25 @@ Append to the `changes` array:- **Tell the user:** "Change logged. Google Ads changes typically take **7 days minimum** to show reliable results (14 days for structural changes like new campaigns or ad copy). I'll check the impact after [reviewAfter date] — you can also ask 'check my changes' anytime."- **Max 200 entries** (remove oldest reviewed first).- **Group related writes** in one session as a single entry.++## Proactive reminders (SessionStart hook + calendar)++Users shouldn't have to remember to come back. Two complementary mechanisms:++1. **SessionStart hook** — `bin/toprank-change-watch` scans every account's `change-log.json` and prints any entry whose `reviewAfter` has passed and `reviewed == false`. Wire it in `~/.claude/settings.json`:+ ```json+ {+ "hooks": {+ "SessionStart": [+ { "hooks": [ { "type": "command", "command": "/home/user/toprank/bin/toprank-change-watch" } ] }+ ]+ }+ }+ ```+ When the user opens a new Claude session, any pending reviews appear as session context — the assistant can proactively offer to run a scoped `/ads-audit`.++2. **Calendar (.ics) reminder** — after logging a change, offer to generate a calendar invite the user can drop into any calendar app:+ ```+ toprank-change-watch ics <account_id> <change_id> > ~/review-<change_id>.ics+ ```+ The .ics file includes a 9-hour-before alarm so the user gets notified on review day. Cross-platform, no cloud dependency, works offline.diff --git a/google-ads/ads/references/quality-score-framework.md b/google-ads/ads/references/quality-score-framework.mdindex 2aa3bd80..89c7555a 100644--- a/google-ads/ads/references/quality-score-framework.md+++ b/google-ads/ads/references/quality-score-framework.md@@ -161,6 +161,8 @@ Google matches exact and phrase match keywords to close variants including:## Landing Page Experience Improvement Playbook+**Before running this playbook manually, offer `/ads-landing`** — it runs the PageSpeed Insights API, scores the page on the 5-dimension rubric, and ranks fixes by expected score delta. Use this playbook only if the user declines the automated score or is diagnosing at the industry-checklist level.+### Landing Page Checklist by Industry| Factor | Target (All Industries) | E-commerce Specific | Lead Gen / Services | SaaS / B2B |diff --git a/google-ads/shared/industry-templates.json b/google-ads/shared/industry-templates.jsonnew file mode 100644index 00000000..e55c8c3a--- /dev/null+++ b/google-ads/shared/industry-templates.json@@ -0,0 +1,196 @@+{+ "_schema_version": "1.0",+ "_description": "Industry presets for Google Ads calibration. Every threshold in analysis-heuristics.md reads from here first, falls back to account-average second. Margins come from commonly cited industry reports and are directional — always override with values from business-context.json when available.",+ "_usage": "Auto-select by matching business-context.json.industry (case-insensitive, substring). If no match, fall back to 'generic'. Prompt the user to confirm the match in Phase 3 intake.",++ "templates": {+ "legal": {+ "aliases": ["law firm", "attorney", "lawyer", "legal services", "personal injury"],+ "typical_margin": 0.7,+ "margin_range": [0.55, 0.85],+ "aov_range_usd": [2500, 15000],+ "target_cpa_range_usd": [70, 150],+ "typical_cvr": 0.075,+ "smart_bidding_min_conv_month": 15,+ "brand_split_expected": { "brand_pct": [15, 35], "nonbrand_pct": [65, 85] },+ "pmax_advisability": "caution",+ "pmax_note": "Lead gen verticals with long qualification cycles often see PMax cannibalize brand and waste on low-quality leads. Prefer Search with Smart Bidding.",+ "recommended_conversion_actions": ["form submit", "phone call (60s+)", "consultation booked"],+ "seasonality_notes": "Personal injury peaks in summer (driving season). Family law peaks in Q1. Business law is steady.",+ "red_flags": ["CPA > $200 with <20 conv/mo", "cost per phone call < 60s", "any 'jobs'/'salary' search terms"],+ "quick_start_negatives": ["jobs", "salary", "free consultation reddit", "pro bono", "legal aid", "how to sue", "do it yourself", "forms download"]+ },++ "home_services": {+ "aliases": ["plumber", "plumbing", "hvac", "electrician", "roofing", "landscaping", "pest control", "cleaning", "handyman", "local service"],+ "typical_margin": 0.4,+ "margin_range": [0.25, 0.55],+ "aov_range_usd": [250, 2500],+ "target_cpa_range_usd": [25, 65],+ "typical_cvr": 0.08,+ "smart_bidding_min_conv_month": 15,+ "brand_split_expected": { "brand_pct": [5, 25], "nonbrand_pct": [75, 95] },+ "pmax_advisability": "not_recommended",+ "pmax_note": "Local service businesses rarely benefit from PMax. Google LSA (Local Services Ads) is usually a better automated option.",+ "recommended_conversion_actions": ["phone call (60s+)", "form submit", "booking scheduled"],+ "seasonality_notes": "HVAC heating Nov-Feb, cooling Jun-Aug. Landscaping Mar-Oct. Roofing Apr-Oct. Most home services spike after storms.",+ "red_flags": ["PRESENCE_OR_INTEREST location targeting", "Search Partners driving 30%+ clicks with 0 conv", "any national search terms"],+ "quick_start_negatives": ["jobs", "salary", "diy", "how to", "youtube", "reddit", "home depot", "lowes", "school", "training", "certification", "license"]+ },++ "healthcare": {+ "aliases": ["dental", "dentist", "dermatology", "medical", "clinic", "urgent care", "physical therapy", "chiropractor", "veterinary"],+ "typical_margin": 0.35,+ "margin_range": [0.25, 0.5],+ "aov_range_usd": [150, 2000],+ "target_cpa_range_usd": [35, 85],+ "typical_cvr": 0.055,+ "smart_bidding_min_conv_month": 20,+ "brand_split_expected": { "brand_pct": [20, 40], "nonbrand_pct": [60, 80] },+ "pmax_advisability": "caution",+ "pmax_note": "HIPAA-sensitive verticals should avoid PMax's broad targeting. Healthcare is a Limited Ads Personalization category — ensure compliance before running any audience targeting.",+ "recommended_conversion_actions": ["appointment booked", "phone call (60s+)", "form submit"],+ "seasonality_notes": "Back-to-school pediatric in Aug-Sep. Dental cleanings Q4 (FSA/HSA spend). Cosmetic procedures spike pre-summer and pre-holiday.",+ "red_flags": ["Limited Ads Personalization not declared", "competitor brand bidding on medical terms (policy risk)", "any health claims in ad copy"],+ "quick_start_negatives": ["jobs", "school", "training", "salary", "free", "reddit", "symptoms checker", "wikipedia", "insurance only"]+ },++ "saas_b2b": {+ "aliases": ["saas", "software", "b2b software", "cloud", "platform", "api", "devtools"],+ "typical_margin": 0.75,+ "margin_range": [0.6, 0.9],+ "aov_range_usd": [500, 50000],+ "target_cpa_range_usd": [60, 250],+ "typical_cvr": 0.035,+ "smart_bidding_min_conv_month": 30,+ "brand_split_expected": { "brand_pct": [25, 50], "nonbrand_pct": [50, 75] },+ "pmax_advisability": "not_recommended",+ "pmax_note": "B2B SaaS rarely benefits from PMax due to long sales cycles and poor display/YouTube quality for B2B intent. Stick with Search + LinkedIn.",+ "recommended_conversion_actions": ["demo request", "trial signup", "qualified lead (MQL)", "pricing page view"],+ "seasonality_notes": "B2B buying cycles slow in Jul-Aug (summer) and Dec-Jan (holidays/budget freeze). Q4 decision spike for annual contracts.",+ "red_flags": ["CPA < $50 (likely trial-only tracking, no qualification)", "optimizing for raw signups vs MQLs", "no LTV signal in conversion values"],+ "quick_start_negatives": ["jobs", "careers", "salary", "training", "certification", "tutorial", "course", "free forever", "open source", "github", "reddit"]+ },++ "ecommerce": {+ "aliases": ["ecommerce", "e-commerce", "shop", "store", "retail", "d2c", "dtc", "shopify"],+ "typical_margin": 0.45,+ "margin_range": [0.25, 0.65],+ "aov_range_usd": [30, 300],+ "target_cpa_range_usd": [10, 50],+ "target_roas": 3.5,+ "typical_cvr": 0.025,+ "smart_bidding_min_conv_month": 30,+ "brand_split_expected": { "brand_pct": [20, 50], "nonbrand_pct": [50, 80] },+ "pmax_advisability": "recommended",+ "pmax_note": "PMax is well-suited to ecommerce with product feeds. Always exclude brand search via brand exclusions to prevent cannibalization.",+ "recommended_conversion_actions": ["purchase (with revenue)", "add to cart", "initiate checkout"],+ "seasonality_notes": "Q4 holiday peak (Nov-Dec). Back to school Aug. Summer dip Jul-Aug for non-seasonal products. BFCM is critical — plan budget 30 days ahead.",+ "red_flags": ["no revenue tracking (tCPA instead of tROAS)", "Shopping feed <80% approved", "missing GTIN/MPN attributes", "PMax without brand exclusion"],+ "quick_start_negatives": ["free", "cheap", "wholesale", "bulk", "reviews only", "manual pdf", "how to return", "cancel order"]+ },++ "finance_insurance": {+ "aliases": ["finance", "insurance", "banking", "loans", "mortgage", "credit", "wealth management", "financial planning"],+ "typical_margin": 0.55,+ "margin_range": [0.35, 0.75],+ "aov_range_usd": [500, 10000],+ "target_cpa_range_usd": [60, 150],+ "typical_cvr": 0.06,+ "smart_bidding_min_conv_month": 20,+ "brand_split_expected": { "brand_pct": [20, 45], "nonbrand_pct": [55, 80] },+ "pmax_advisability": "caution",+ "pmax_note": "Finance is a Special Ad Category (credit/housing/employment). Must declare to Google. Audience targeting is restricted — PMax audience signals are limited.",+ "recommended_conversion_actions": ["application submitted", "quote requested", "phone call (90s+)"],+ "seasonality_notes": "Tax season Jan-Apr drives loan/refi demand. Open enrollment Oct-Dec for health/Medicare. New Year resolutions drive budgeting tools in Jan.",+ "red_flags": ["Special Ad Category not declared", "any superlative claims ('best rate', '#1')", "unqualified leads driving down CVR"],+ "quick_start_negatives": ["jobs", "salary", "free", "scam", "reddit", "calculator only", "definition", "what is"]+ },++ "real_estate": {+ "aliases": ["real estate", "realtor", "broker", "property", "homes for sale", "rentals", "property management"],+ "typical_margin": 0.6,+ "margin_range": [0.4, 0.8],+ "aov_range_usd": [5000, 30000],+ "target_cpa_range_usd": [40, 120],+ "typical_cvr": 0.035,+ "smart_bidding_min_conv_month": 15,+ "brand_split_expected": { "brand_pct": [10, 30], "nonbrand_pct": [70, 90] },+ "pmax_advisability": "caution",+ "pmax_note": "Housing is a Special Ad Category — audience targeting restricted (age, gender, ZIP, parental status excluded). PMax signals must comply.",+ "recommended_conversion_actions": ["property inquiry", "showing scheduled", "phone call (60s+)"],+ "seasonality_notes": "Spring buying season Mar-Jun is peak. Summer steady. Q4 slowdown. Rentals peak in summer for student/family moves.",+ "red_flags": ["Special Ad Category not declared", "non-compliant audience targeting", "wide geo-targeting (should be neighborhood-level)"],+ "quick_start_negatives": ["zillow", "redfin", "trulia", "free", "rent to own", "foreclosure list", "jobs", "license", "school"]+ },++ "education": {+ "aliases": ["education", "school", "university", "online course", "tutoring", "training", "certification", "bootcamp"],+ "typical_margin": 0.65,+ "margin_range": [0.45, 0.85],+ "aov_range_usd": [200, 15000],+ "target_cpa_range_usd": [30, 120],+ "typical_cvr": 0.055,+ "smart_bidding_min_conv_month": 20,+ "brand_split_expected": { "brand_pct": [15, 35], "nonbrand_pct": [65, 85] },+ "pmax_advisability": "caution",+ "pmax_note": "Employment is a Special Ad Category if the program leads to a career — must declare. Otherwise PMax is viable with strong audience signals.",+ "recommended_conversion_actions": ["application submitted", "info request", "trial lesson booked", "enrollment"],+ "seasonality_notes": "Back-to-school Jul-Sep is peak. New Year resolution spike Jan. Summer programs Apr-Jun. Avoid scaling in Dec (holiday lull).",+ "red_flags": ["employment category not declared for career programs", "no differentiation between inquiry and enrollment"],+ "quick_start_negatives": ["free", "reddit", "scholarship", "fafsa", "jobs", "salary", "syllabus download"]+ },++ "travel_hospitality": {+ "aliases": ["travel", "hotel", "airline", "tourism", "booking", "vacation", "hospitality", "restaurant"],+ "typical_margin": 0.3,+ "margin_range": [0.15, 0.5],+ "aov_range_usd": [100, 3000],+ "target_cpa_range_usd": [15, 60],+ "target_roas": 5.0,+ "typical_cvr": 0.045,+ "smart_bidding_min_conv_month": 30,+ "brand_split_expected": { "brand_pct": [25, 55], "nonbrand_pct": [45, 75] },+ "pmax_advisability": "recommended",+ "pmax_note": "Travel benefits from PMax's multi-format approach. Use feeds where possible (hotel, flight). Always exclude brand.",+ "recommended_conversion_actions": ["booking completed (with revenue)", "search initiated", "contact form"],+ "seasonality_notes": "Highly seasonal by destination. Summer travel books in Mar-May. Holiday travel Oct-Nov. Weather-dependent spikes.",+ "red_flags": ["no revenue tracking", "OTA competitors outbidding direct bookings", "wide date-targeting without seasonality adjustments"],+ "quick_start_negatives": ["free", "jobs", "salary", "photos", "wiki", "weather", "map", "reviews only"]+ },++ "automotive": {+ "aliases": ["automotive", "auto", "car dealer", "dealership", "auto repair", "auto parts"],+ "typical_margin": 0.35,+ "margin_range": [0.2, 0.55],+ "aov_range_usd": [200, 3000],+ "target_cpa_range_usd": [30, 70],+ "typical_cvr": 0.065,+ "smart_bidding_min_conv_month": 20,+ "brand_split_expected": { "brand_pct": [15, 35], "nonbrand_pct": [65, 85] },+ "pmax_advisability": "caution",+ "pmax_note": "Dealers see mixed results with PMax. Vehicle ads (new format) preferred for inventory feeds. Service ads work better in Search.",+ "recommended_conversion_actions": ["phone call (60s+)", "form submit", "test drive booked", "service appointment"],+ "seasonality_notes": "Spring/summer peak for purchases. Fall for service (winterization). Year-end clearance Dec. Tax season for repairs.",+ "red_flags": ["inventory not synced to vehicle ads", "wide geo (should be 25mi radius)", "unused service extensions"],+ "quick_start_negatives": ["jobs", "reviews only", "blue book", "kbb", "carfax", "recall", "free", "pictures"]+ },++ "generic": {+ "aliases": [],+ "typical_margin": 0.4,+ "margin_range": [0.25, 0.6],+ "aov_range_usd": [100, 1000],+ "target_cpa_range_usd": [30, 80],+ "typical_cvr": 0.04,+ "smart_bidding_min_conv_month": 20,+ "brand_split_expected": { "brand_pct": [15, 40], "nonbrand_pct": [60, 85] },+ "pmax_advisability": "caution",+ "pmax_note": "Without industry-specific context, PMax should be tested in isolation before scaling. Always exclude brand.",+ "recommended_conversion_actions": ["form submit", "phone call", "purchase"],+ "seasonality_notes": "Unknown — ask the user or infer from historical month-over-month patterns.",+ "red_flags": ["no industry-specific conversion action", "missing business-context.json"],+ "quick_start_negatives": ["jobs", "salary", "free", "reddit", "wikipedia", "definition"]+ }+ }+}diff --git a/google-ads/shared/ppc-math.md b/google-ads/shared/ppc-math.mdnew file mode 100644index 00000000..62079e12--- /dev/null+++ b/google-ads/shared/ppc-math.md@@ -0,0 +1,135 @@+# PPC Math — Margin-Aware Profitability Calculators++Formulas and interpretation rules used throughout the Google Ads skills. Load this when a finding needs dollar-denominated impact, profitability framing, or a forecast.++**Priority rule:** When `business-context.json` has `profit_margin` and `aov`, use break-even-based thresholds. Otherwise fall back to account-average heuristics in `analysis-heuristics.md`. Never mix the two in a single finding — the framing should be consistent.++---++## Core Formulas++```+CPA = Spend / Conversions+ROAS = Revenue / Spend (ratio, e.g. 3.5x)+ROAS% = (Revenue - Spend) / Spend × 100+CPC = Spend / Clicks+CPM = (Spend / Impressions) × 1000+CTR = Clicks / Impressions × 100+CVR = Conversions / Clicks × 100+CPL = Spend / Leads+```++## Profitability Formulas (require margin + AOV)++```+Break-Even CPA = AOV × Profit Margin+Max Profitable CPA = Break-Even CPA (bid up to this, no higher)+Break-Even ROAS = 1 / Profit Margin+Unit Profit = AOV × Profit Margin - CPA+Headroom $ = (Break-Even CPA - Current CPA) × Monthly Conversions+```++**Headroom interpretation:**++| Headroom | Framing | Action |+|---|---|---|+| Negative | "Losing $X/month on this campaign" | Pass 1 — pause or restructure immediately |+| $0-$500/mo | "Barely break-even" | Pass 3 — improve QS/CVR before scaling |+| $500-$2,000/mo | "Profitable but tight" | Pass 2 — selective scaling |+| >$2,000/mo | "Strong unit economics" | Pass 2 — scale aggressively (20% rule) |++---++## LTV:CAC (require LTV data)++```+CAC = Total Marketing Spend / New Customers Acquired+LTV = ARPU × Avg Customer Lifespan (or use business-context.json.ltv if set)+LTV:CAC = LTV / CAC+Payback = CAC / (ARPU × Gross Margin) (months to recover CAC)+```++| LTV:CAC | Interpretation |+|---|---|+| <1:1 | Losing money on every customer. Stop scaling immediately |+| 1:1–3:1 | Marginal. Viable only if payback period < 12 months |+| 3:1 | Healthy (SaaS/service benchmark) |+| 5:1+ | Under-investing in growth. You can afford to bid higher |++---++## Impression Share Opportunity++```+Revenue Opportunity = Current Revenue × (1 / Current IS - 1)+Budget to Capture Full IS = Current Spend × (1 / Current IS)+```++**Example:** Campaign at 60% IS, spending $3,000/mo, generating $12,000 revenue.+- Full-IS revenue potential: $12,000 × (1/0.6 - 1) = **$8,000/mo additional**+- Budget to capture it: $3,000 × (1/0.6) = **$5,000/mo**+- Incremental: spend $2,000 more → capture $8,000 more revenue (4x ROAS on incremental)++**Only use this framing when Budget-Lost IS is the constraint (Layer 4 Scale).** If Rank-Lost IS is the constraint, increasing budget does nothing — the formula mis-frames the problem.++---++## Budget Forecasting++```+Projected Spend = Daily Budget × Days in Period+Projected Conversions = Projected Spend / Historical CPA+Projected Revenue = Projected Conversions × AOV+```++Present 3 scenarios, enforcing the **20% scaling rule** (never recommend more than +20% in a single week; compound across weeks):++| Scenario | Weekly Budget Increase | Caveat |+|---|---|---|+| Conservative | +20% | Safest — no learning phase reset |+| Moderate | +50% over 3 weeks (+20%, +25%, +25% compounded) | Monitor for CPA drift after each step |+| Aggressive | +100% over 5 weeks | Diminishing returns kick in; expect CPA to rise 15–25% |++Always show the **diminishing returns warning** for aggressive: "Doubling budget rarely doubles conversions — expect 1.5–1.7x conversions at 2x spend."++---++## MER (Marketing Efficiency Ratio)++```+MER = Total Business Revenue / Total Marketing Spend+```++Use MER when the user has multi-channel spend and wants blended efficiency. Typical ranges by industry template (see `industry-templates.json`):++| Industry | Typical MER | Excellent |+|---|---|---|+| Ecommerce | 3–5x | 8x+ |+| SaaS | 5–10x | 15x+ |+| Local Service | 3–8x | 10x+ |++MER captures organic, brand, and retention — so it's higher than paid ROAS and should never be compared directly to ROAS.++---++## Usage in Findings++**Before (account-average framing):**+> "Keyword 'emergency plumber seattle' has CPA of $72, which is 150% of account average."++**After (margin-aware framing, requires `margin=0.4`, `aov=$180` from business-context.json):**+> "Keyword 'emergency plumber seattle' has CPA of $72. Your Break-Even CPA is $72 (AOV $180 × 40% margin) — every conversion from this keyword nets $0 profit. Either improve CVR or pause."++**Headroom example:**+> "Tukwila Search is profitable: CPA $18, Break-Even $72, **~$2,700/mo headroom** at 50 conversions. Budget-Lost IS is 35% — raising budget by $1,500/mo could capture ~$5,000 more revenue."++The second framing is concretely actionable. The first is a number without a verdict.++---++## Gates++1. **Never compute break-even without verified margin.** If `business-context.json.profit_margin` is missing or marked `inferred_from_template`, label the output "estimated from industry template (±20%)" and ask the user to confirm before any write operation.+2. **Never project conversions more than 2x current spend.** Diminishing returns make linear projections unreliable beyond that.+3. **Never use MER in place of ROAS for individual-campaign decisions.** MER is a blended portfolio metric; individual campaigns must clear ROAS/CPA targets.+4. **LTV:CAC requires ≥12 months of history.** If the business is newer, fall back to payback period only.