---
name: analyze-search-term-reports
description: >-
  The recurring query-hygiene pass over Search traffic: scans the search term report for queries that are plainly
  unrelated to the business and negates them into a shared exclusion list, and separately flags converting,
  not-yet-added terms as promotion candidates. Relevance judgment only, it deliberately refuses to negate on CPA
  or ROAS numbers, because single-term performance is noise; that job belongs to run-n-gram-analysis. Use it weekly
  in a campaign's first month, bi-weekly to 90 days, monthly after, and immediately after new match types, products,
  or seasonal promos change the traffic mix. Actual keyword additions route to promote-search-terms-to-keywords;
  keyword-level scoring lives in analyze-and-optimize-keyword-performance.
---
# Search Term Report Hygiene

## Purpose
Search term reports answer two different questions that should never be blended: which queries have no business
matching your ads at all, and which queries are so good they deserve keyword status. This skill runs both scans on a
cadence, applies the negations, and hands promotion candidates to the dedicated promotion skill, while explicitly
refusing to make performance-based negation calls that single-term data cannot support.

## When to run
- Recurring cadence: weekly for the first 30 days after launch, bi-weekly from 30–90 days, monthly once mature.
- A new match type, campaign type, or keyword expansion just went live (discovery traffic spikes).
- A seasonal promotion or new product line is pulling in unfamiliar query patterns.
- A spend-without-relevance complaint: "why did we show for X?"

## When NOT to run
- You want to cut terms because their CPA is bad → `run-n-gram-analysis` (aggregated patterns, not single terms).
- You already have promotion candidates and want to add them properly → `promote-search-terms-to-keywords`.
- You are scoring keywords, not queries → `analyze-and-optimize-keyword-performance`.
- The report window has near-zero impressions, wait for data instead of negating on guesses.

## Prerequisites
- Analysis window matched to cadence: 7 days (weekly), 14 (bi-weekly), 30 (monthly).
- The current keyword list per ad group, for duplicate checks during the promotion scan.
- A shared negative list dedicated to irrelevant terms exists and is linked to the right campaigns (if it does not,
  create it in step 6 before applying anything).
- Enough business context to judge relevance, if the agent cannot tell whether a term fits the business, it asks
  the user rather than negating.

## Procedure
1. **Export the data.** Call `gads_get_search_terms_report` for all in-scope campaigns over the cadence window,
   including impressions, clicks, cost, conversions, the matched keyword, ad group, and added/excluded status.
   Drop zero-impression rows. Sort the working set alphabetically by query, adjacent sorting clusters related
   phrasings so a bad word surfaces as a visible run of rows instead of scattered one-offs.
2. **Shield the converters.** Before any relevance scanning, set aside every term with 1+ conversions. Converting
   terms are never negated in this skill no matter how odd they look, if a strange query converts, the data is
   overruling the intuition.
3. **Scan for irrelevance by theme, not by term.** Walk the remaining list looking for words and themes with no
   connection to the business: job-seeker language, purely informational phrasing when the account targets buyers,
   competitor brands (when not deliberately bidding on them), products the business does not sell, spam/adult
   noise. Build categories dynamically from what the account actually shows, require 3+ similar terms before
   declaring a category, and name it by the intent it represents. This is an LLM-plus-human judgment step: present
   the proposed categories with example queries and let the user veto before anything is applied.
4. **Respect the approximation caveat.** Terms sourced from AI-assisted and visual search surfaces are Google's
   reconstruction of intent, not verbatim queries. Never negate a single oddly-worded term on its literal reading;
   only negate patterns confirmed across multiple rows (or defer to `run-n-gram-analysis`).
5. **Build the promotion candidate list.** Filter to terms with 1+ conversions AND added/excluded status of
   "None" AND enough volume: 100+ impressions in high-volume accounts (1,000+ clicks/month/campaign), 50+ in
   mid-volume, or simply the top 10 converting terms in low-volume accounts. Record each with its conversions,
   CVR, cost per conversion, and triggering keyword. Do not add keywords here, hand the list to
   `promote-search-terms-to-keywords`.
6. **Consult the policy guardrail, then apply negations.** Call `gads_policy_guardrail` before the session's first
   Google Ads write. Then add the approved irrelevant terms to the shared irrelevant-terms exclusion list:
   `gads_add_negatives_from_search_terms` when negating directly from report rows, or `gads_add_negative_keywords`
   / `gads_add_keywords_to_shared_set` for hand-formatted entries. All negatives phrase match, lowercase, no
   punctuation. Preview first (validate_only default); commit only after explicit user approval. Add singular and
   plural forms separately, negatives do not expand to close variants, so "job" does not block "jobs".
7. **Check for conflicts.** After the commit, run `gads_run_gaql_query` against the campaign criterion and shared
   set data to confirm no new negative collides with an active positive keyword, and spot-check that ads still
   serve on the account's highest-value terms.
8. **Log the cycle.** Record window analyzed, terms reviewed, categories found, negatives added, promotion
   candidates handed off, and any deferred borderline terms with a revisit date. The deferral list is the memory
   that keeps borderline calls from being re-argued every cycle.

## Decision rules
- **Negate on relevance only.** A term qualifies for negation here if the business could never fulfill its intent, not because its CPA is high. High-CPA-but-relevant patterns go to `run-n-gram-analysis` once aggregated.
- **Converting terms are untouchable** in this skill, regardless of apparent relevance.
- **Category floor:** 3+ similar terms before creating a named irrelevance category; below that, treat as one-off
  and defer.
- **Match type for negatives:** phrase match as the default for everything, including single words, it blocks the
  word/sequence without broad-negative's any-order over-blocking.
- **Promotion eligibility:** conversions ≥ 1 AND not already a keyword AND volume floor met (100/50 impressions or
  top-10 rule by account size).
- **When unsure, keep the traffic.** An uncertain term stays live with a note; if it is genuinely wasteful it will
  surface with statistical weight in the next N-gram pass.
- **Cadence resets** when discovery-heavy changes ship (new match types, new campaign types, new products): drop
  back to weekly for a month.

## Common failure modes
- **Performance-negating single terms.** One term's bad CPA on 12 clicks is noise; negating it teaches you nothing
  and slowly strangles reach. The relevance/performance split is the core discipline of this skill.
- **Negating a good keyword's close variant.** Always run the conflict check (step 7), the most expensive negative
  is the one blocking your own best keyword.
- **Skimming only the top of the report.** The alphabetical full-list walk exists because irrelevant themes hide in
  the long tail; cost-sorted skimming misses them.
- **One-word broad negatives.** They block far more than intended; phrase match with explicit variants is slower to
  type and much safer.
- **Forgetting variant coverage.** Negating "job" and wondering why "jobs" still bleeds. Add each form.
- **Promoting inline.** Adding keywords mid-scan without the promotion framework fragments Smart Bidding data;
  hand candidates off instead.
- **No decision log.** Without the deferral list, next cycle re-reviews the same borderline queries with the same
  missing context.

- **Blanket negation across campaign types without checking scope.** A term irrelevant to the lead-gen campaign
  may be a legitimate query for the support-content campaign; confirm which campaigns the shared list touches
  before adding, and use campaign-level negatives for genuinely campaign-specific blocks.
- **Reviewing cost-sorted instead of alphabetized.** Cost sorting front-loads what already spends; the
  alphabetical pass is what reveals that a single bad word spans thirty cheap terms about to become expensive.

## Follow-up checks after each cycle
- Within 7 days: spot-check that newly promoted keywords accrue impressions and match their intended queries.
- Within 7 days: spot-check that ads still serve on the highest-value terms, the fastest tripwire for an
  over-broad negative.
- Next cycle: open with the deferral list before pulling fresh data, so borderline calls resolve instead of
  recycling.

## Related skills
- Run after this: `promote-search-terms-to-keywords` (executes the candidate list), `run-n-gram-analysis`
  (performance-pattern negation on its own cadence).
- Run when diagnosis points elsewhere: `improve-ad-relevance` if promoted keywords land with weak QS,
  `audit-and-optimize-an-existing-landing-page` if terms reveal an intent/page mismatch.
- Orchestrated by: `run-search-campaign-optimization-cycle` as its query-management phase.