{
  "skill_name": "google-ads-audit",
  "evals": [
    {
      "id": 1,
      "prompt": "Run a full audit of my Google Ads account. Here's the data:\n\n```json\n{\"account\": {\"name\": \"Bay Area Roofing Co\", \"id\": \"9876543210\", \"currency\": \"USD\", \"timezone\": \"America/Los_Angeles\", \"auto_tagging\": true},\n\"campaigns\": [{\"name\": \"Brand\", \"spend\": 800, \"clicks\": 420, \"impressions\": 5200, \"conversions\": 38, \"cpa\": 21.05, \"ctr\": 8.1, \"budget_lost_is\": 5, \"rank_lost_is\": 10}, {\"name\": \"Roof Repair\", \"spend\": 3200, \"clicks\": 580, \"impressions\": 14000, \"conversions\": 22, \"cpa\": 145.45, \"ctr\": 4.1, \"budget_lost_is\": 35, \"rank_lost_is\": 25}, {\"name\": \"Gutter Cleaning\", \"spend\": 1500, \"clicks\": 390, \"impressions\": 8800, \"conversions\": 28, \"cpa\": 53.57, \"ctr\": 4.4, \"budget_lost_is\": 12, \"rank_lost_is\": 15}],\n\"keywords\": [{\"campaign\": \"Roof Repair\", \"keyword\": \"roof repair near me\", \"spend\": 1100, \"clicks\": 180, \"conversions\": 12, \"qs\": 7}, {\"keyword\": \"premium roof repair\", \"campaign\": \"Roof Repair\", \"spend\": 900, \"clicks\": 120, \"conversions\": 2, \"qs\": 4}, {\"keyword\": \"cheap roof repair\", \"campaign\": \"Roof Repair\", \"spend\": 650, \"clicks\": 140, \"conversions\": 0, \"qs\": 3}, {\"keyword\": \"roofing jobs\", \"campaign\": \"Roof Repair\", \"spend\": 280, \"clicks\": 65, \"conversions\": 0, \"qs\": 2}, {\"keyword\": \"gutter cleaning san francisco\", \"campaign\": \"Gutter Cleaning\", \"spend\": 800, \"clicks\": 210, \"conversions\": 20, \"qs\": 9}],\n\"conversion_actions\": [{\"name\": \"Phone Call\", \"type\": \"PHONE_CALL\", \"status\": \"ENABLED\"}, {\"name\": \"Form Submit\", \"type\": \"WEBPAGE\", \"status\": \"ENABLED\"}],\n\"search_terms\": [{\"term\": \"roof repair san francisco\", \"clicks\": 45, \"conversions\": 8, \"spend\": 270}, {\"term\": \"how to start a roofing business\", \"clicks\": 32, \"conversions\": 0, \"spend\": 190}, {\"term\": \"roof repair prices\", \"clicks\": 28, \"conversions\": 3, \"spend\": 140}],\n\"ads_per_group\": {\"Roof Repair - General\": 1, \"Gutter Cleaning - SF\": 3}}\n```",
      "expected_output": "A comprehensive audit with three pulse metrics (Waste $/mo, Demand captured %, CPA $) plus per-area findings. Should identify: Roof Repair campaign has 35% budget-lost IS (severe constraint) AND 25% rank-lost IS (both dimensions problematic — relevance fix first per the 2x2 matrix). 'cheap roof repair' and 'roofing jobs' are waste ($930 combined, 0 conversions). 'premium roof repair' has QS 4 and poor CPA. Roof Repair ad group has only 1 RSA (needs more). Conversion tracking exists but is basic (no enhanced conversions). Should recommend adding 'roof repair san francisco' as keyword (8 conversions). Should flag 'how to start a roofing business' as negative.",
      "files": [],
      "expectations": [
        "Reports three pulse metrics (Waste, Demand captured, CPA) with named top contributor and a fix pointer for each",
        "Does NOT emit a 0-5 dimension score or a numeric overall health score",
        "Identifies Roof Repair campaign's impression share problem using the 2x2 matrix (budget-lost 35% + rank-lost 25%) and recommends fixing relevance before adding budget",
        "Identifies 'cheap roof repair' ($650, 0 conv) and 'roofing jobs' ($280, 0 conv) as wasted spend with specific dollar amounts",
        "Flags 'premium roof repair' QS 4 as needing quality improvement",
        "Notes Roof Repair ad group has only 1 RSA and recommends adding more",
        "Recommends adding 'roof repair san francisco' as a keyword (8 conversions from search terms)",
        "Recommends adding 'how to start a roofing business' as a negative keyword",
        "Quick Wins section present (or top actions with dollar impact) — every claim cites specific entities and numbers"
      ]
    },
    {
      "id": 2,
      "prompt": "Audit my Google Ads account. Here's the data:\n\n```json\n{\"account\": {\"name\": \"Quick Print Co\", \"id\": \"1112223334\", \"currency\": \"USD\"},\n\"campaigns\": [{\"name\": \"All Services\", \"spend\": 2500, \"clicks\": 800, \"impressions\": 20000, \"conversions\": 0, \"cpa\": null, \"ctr\": 4.0}],\n\"conversion_actions\": [],\n\"keywords\": [{\"keyword\": \"printing services\", \"spend\": 800, \"clicks\": 260, \"conversions\": 0, \"qs\": 5}, {\"keyword\": \"business cards\", \"spend\": 600, \"clicks\": 200, \"conversions\": 0, \"qs\": 6}]}\n```",
      "expected_output": "The audit should immediately flag that conversion tracking is completely missing (no conversion actions at all). This is the STOP condition — the audit halts and recommends pausing spend until tracking is fixed. The Waste pulse metric should apply the signal-failure override (cannot compute — conversion tracking broken). The entire $2500 in spend cannot be evaluated for ROI. The #1 recommendation must be to set up conversion tracking before any other optimization.",
      "files": [],
      "expectations": [
        "Flags missing conversion tracking as the #1 critical issue",
        "Applies the signal-failure override on the Waste pulse metric (does not report a dollar waste figure when tracking is broken)",
        "States that the $2500 spend cannot be evaluated without conversion tracking",
        "Recommends setting up conversion tracking as the first action before any keyword or bid optimization",
        "Does not recommend bid or keyword changes since there's no conversion data to base decisions on"
      ]
    }
  ]
}

# Account Health — Diagnostic Reference

Domain knowledge and the audit's structured output format. **Not a checklist.** Pull this account's data, find what's actually broken, and let the data drive the recommendation. Every claim cites specific entities, numbers, and time windows (per `../../shared/analysis-principles.md`).

---

## The seven areas to look at

These are where you look for evidence — not boxes to grade.

| Area | The question it answers |
|---|---|
| Signal Quality | Can I trust the data? |
| Campaign Structure | Am I in the right auctions, organized so each one makes sense? |
| Keyword Health | Are my keywords pulling weight, or burning money? |
| Search Term Quality | Are queries reaching me actually relevant? |
| Ad Copy & Creative | Are my ads competitive once an auction starts? |
| Impression Share | Why am I losing the auctions I lose? |
| Spend Efficiency | Where is the money going, and is it producing customers? |

---

## Signal Quality — diagnostic facts

If signals are broken, every downstream decision is built on lies. Smart Bidding can't optimize what it can't measure. Patterns to recognize:

- **0 conversions in 30 days with spend > 5× account CPA** → tracking is almost certainly broken or missing.
- **Conversion rate > 50%** → tag firing on page load, not on actual conversions.
- **All conversions = "Website" with no action names** → default tracking only; no segmentation.
- **Last-click attribution** → deprecated since 2023; data-driven attribution is the only model accepted for new conversion actions. Existing conversion actions on last-click should migrate.
- **Smart Bidding (tCPA / tROAS) with < ~15 conversions/month** → insufficient data density for the algorithm to learn (typical floor is 30+ for tCPA, 50+ for tROAS).
- **Missing Consent Mode v2 with EU traffic** → degraded conversion modeling in privacy-regulated markets; bid strategies underperform.
- **Enhanced conversions disabled** → cross-device / cross-browser attribution gaps; Smart Bidding is missing signal.

**STOP condition:** if Signal Quality is broken, recommend pausing spend until it's fixed before any other recommendation.

---

## Impression Share — the most important read in the audit

Rank-lost-IS and budget-lost-IS are two different problems with two different fixes. Treating them as one "impression share problem" produces bad advice — telling someone with a relevance problem to spend more burns money faster.

- **Lost IS (Rank)** = relevance problem. Ad Rank is low; the auction is telling you the ads, themes, or landing page aren't competitive. Fix with better creative, tighter themes, better landing pages — not more money.
- **Lost IS (Budget)** = scaling opportunity. You're winning auctions but running out of gas. Fix with more budget or narrower targeting, *if* the campaign is profitable.

**The 2×2:**

| | Rank-Lost IS LOW | Rank-Lost IS HIGH |
|---|---|---|
| **Budget-Lost IS LOW** | Healthy — optimize at the margins | Relevance problem — fix QS / ads / pages, do **not** add budget |
| **Budget-Lost IS HIGH** | Capital problem — add budget if profitable, or narrow geo / daypart | Structural problem — wrong keywords or wrong audience entirely; rebuild |

**Data caveat:** impression-share metrics in GAQL only return up to 90 days. Don't use `LAST_365_DAYS` on any query that selects `metrics.search_*_impression_share`.

---

## Wasted spend — formula

Wasted spend is three things, summed and de-duplicated:

```
Keyword waste     = Spend on Tier 2/3 keywords with 0 conversions AND clicks past significance gate
Search-term waste = Spend on search terms with low relevance (irrelevant intent, clear non-buyer signals)
Structural waste  = Spend on Display Network impressions inside Search-channel campaigns
                    (network_settings.target_content_network = TRUE on a SEARCH campaign)
```

**De-duplicate:** search-term waste from a wasted keyword is already counted in keyword waste — don't double-count. Tier 1 (core) keyword underperformance is an optimization opportunity, not waste.

---

## Brand vs. non-brand — the most misleading rollup

Many accounts show great overall ROAS where the majority comes from brand traffic — paying Google a tax on existing customers, not acquiring new ones. Always report the split:

> "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, that itself is a structural finding. PMax running alongside Search with declining brand impression-share = cannibalization; flag and recommend brand exclusions.

---

## Pulse Metrics — the audit's headline output

The audit doesn't emit a letter grade or a 0–5 score. It surfaces **three pulse metrics**, each annotated with its biggest contributor and a pointer to the fix. The metric IS the verdict — read it as dollars and act on it directly.

Every pulse metric answers 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?** (specific handoff or action)

### The three metrics

| Metric | Measures | Better = | Compute |
|---|---|---|---|
| **Waste** | $/mo burning on zero-conversion spend | Lower | Wasted-spend formula above, extrapolated to 30 days |
| **Demand captured** | % of eligible impressions won on profitable campaigns | Higher | Spend-weighted avg `search_impression_share` across campaigns with ≥ 1 conversion. If `unit_economics` exists, filter to campaigns with `CPA ≤ Break-Even CPA` |
| **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

**Waste line.** Dollar value extrapolated to 30 days (`$X/mo, Y% of spend`) + top contributor (keyword / search term / campaign) + pointer to the fix.
- *Signal-failure override:* if conversion tracking is broken, replace the dollar figure with `⚠️ Cannot compute — conversion tracking broken` and point to the tracking fix. Waste is meaningless when conversions can't be measured.

**Demand-captured line.** Percentage + top single opportunity (campaign + headroom in $/mo, margin-aware where possible) + pointer.
- *Relevance override:* if rank-lost-IS > 30% on the named campaign, flag that more budget won't help — "fix relevance first" — and point at the relevance fix instead.

**CPA line.** Dollar value + context (`vs industry $Y–$Z` from `industry-templates.json`, or `vs break-even $Y` from `unit_economics`) + the single biggest structural driver if CPA is unhealthy (which campaign is pulling it up; which QS component is below average).

### Quick Wins section

After the pulse metrics and per-area findings, 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 top). Max 5 items. If none qualify, omit the section — don't fabricate.

Every Quick Win includes the executable command where applicable. Examples:
- `Add 7 negatives to Example City Search — saves ~$340/mo (<5 min) · /google-ads add negatives to Example City Search: jobs, careers, salary, diy, free, reddit, training`
- `Enable Enhanced Conversions — unblocks measurement (<15 min) · Configure in Google Ads UI`

### `time_to_fix` field

Every finding carries `time_to_fix ∈ <5min | <15min | <30min | <2h | >2h`. This is how long the fix takes, not how important it is. The dollar figure carries priority — sort and filter on dollars.

### Persisting to `audit-history.json`

```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 estimate' — $340/mo",
      "tracking_blocker": false
    },
    "demand_captured": {
      "pct": 42.7,
      "top_opportunity": "Example City 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 estimate' keyword ($120 waste)",
    "Budget-lost IS 40% on Example City Search at $14 CPA"
  ],
  "next_milestone": null
}
```

On re-audits, diff the three numbers directly:

- `Waste: $640/mo (4.1%) _(was $1,240/mo — 3 fixes applied)_`
- `Demand captured: 58% _(was 42% — Example City 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.

---

## Industry CPA Benchmarks — calibration anchors

Directional benchmarks for evaluating spend efficiency. Actual CPA varies by market, geography, competition, and offer — use as a reference point, not an absolute target. Always prefer `unit_economics.break_even_cpa` when available.

| Industry | Avg CPA (Search) | Good | Excellent |
|----------|------------------|------|-----------|
| Legal | $85–$120 | <$70 | <$50 |
| Home Services | $40–$65 | <$35 | <$25 |
| Healthcare | $55–$85 | <$50 | <$35 |
| B2B / SaaS | $75–$120 | <$65 | <$45 |
| E-commerce | $30–$50 | <$25 | <$15 |
| Finance / Insurance | $70–$110 | <$60 | <$40 |
| Real Estate | $50–$80 | <$45 | <$30 |
| Education | $45–$75 | <$40 | <$25 |
| Travel | $35–$60 | <$30 | <$20 |
| Automotive | $40–$65 | <$35 | <$25 |

# Business Context — Website Crawl & Data Collection

This reference covers the website crawl procedure and business context JSON schema used by the `/google-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 already pulled in Phase 1 (the `ad_group_ad` rows from the audit dataset) — 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": "",
  "industry_template_key": "",
  "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": []
  },
  "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": {},
  "notes": "",
  "audit_date": "",
  "account_id": ""
}
```

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 dollar-impact figure in the audit. 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.

# Conversion + Network Integrity Audit

Use this during first-time audits, regression explanations, Smart Bidding/budget recommendations, Search Partners questions, or any account where CPA/ROAS looks suspicious.

Bid, budget, negative, and ad-test decisions are only as good as the conversion and traffic segment data behind them. Measurement and network mix are prerequisite checks, not afterthoughts.

---

## 1. Conversion tracking integrity

Pull conversion-action inventory and campaign conversion settings before recommending aggressive optimization.

Check:

- Enabled primary conversion actions exist and match the business goal.
- Lead-gen counting is normally `ONE_PER_CLICK`; purchases/subscriptions may be `MANY_PER_CLICK`.
- Conversion values/currencies are present and sane when using value-based bidding.
- Imported/read-only actions are not treated as mutable API targets.
- Campaign-specific goals do not optimize one campaign for irrelevant actions.
- Duplicate actions/tags are not double-counting the same event.
- Offline/call/form coverage matches how revenue actually happens.
- Recent zero-conversion cliffs are not caused by tag/site/form changes.

Stop condition:

- If tracking is materially broken, say so and recommend fixing measurement before bid/budget changes. Do not optimize on bad signal.

---

## 2. Network segmentation

Use for Search Partners, Display-in-Search leakage, unexplained CPA/CVR shifts.

Pull by `segments.ad_network_type` when compatible:

- cost, clicks, impressions, conversions, conversion value
- CTR, CVR, CPA/ROAS
- campaign/ad group
- search terms where available

Interpretation:

- **Google Search better, Partners material and worse:** recommend disabling Search Partners or testing without them.
- **Partners better or similar:** keep, but monitor because partner mix is opaque and can shift.
- **Tiny partner volume:** do not overreact.
- **Display Network in Search campaign:** flag as structural leakage unless intentionally enabled.

Search Partners decision must be based on the account's goal metric, not CTR alone. A lower CTR partner segment can still be profitable; a high CTR segment can still produce junk leads.

---

## 3. Regression lens

When conversions or CVR change, split the diagnosis:

- Traffic volume changed: impressions/clicks/search demand/impression share.
- Traffic quality changed: search terms, network, match type, geography/device.
- Conversion rate changed: landing page, tracking, form, offer, site speed.
- Bidding changed: strategy, targets, learning, budget caps.
- Measurement changed: conversion actions, primary flags, tag health, offline import.

Always overlay recent changes from NotFair changes and Google `change_event` before attributing causality.

---

## Sources

- `../../shared/ppc-optimization-pattern-playbook.md` — conversion tracking, Search Partners, and conversion-change diagnosis modules.
- General conversion tracking, Search Partners evaluation, assisted conversions, and KPI monitoring patterns.

# 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 | Where it lives in the audit dataset |
|--------|----------------|---------------|
| Search terms | What customers actually search for — their language, pain points, urgency | `search_term_view` rows |
| Converting keywords | What they buy — terms that lead to conversions reveal purchase intent | `keyword_view` rows filtered to `metrics.conversions > 0` |
| Ad-group themes | How the business segments services — each theme may serve a different persona | `ad_group.name` distribution |
| Landing page URLs | Where they land — different pages suggest different customer journeys | `ad_group_ad.ad.final_urls` |
| Geographic data | Where they are — metro vs rural, specific cities | `campaign_criterion` LOCATION + PROXIMITY rows |
| Device split | How they search — mobile-heavy suggests on-the-go / urgent need | Segment any `metrics.*` query by `segments.device` |
| Time-of-day patterns | When they search — business hours vs. evenings vs. weekends | Segment by `segments.day_of_week` and `segments.hour` |

## 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 `/google-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 `/google-ads-copy` for headline generation and `/google-ads` for keyword strategy.