--- name: promote-search-terms-to-keywords description: >- Decides which live search queries earn their own keyword and executes the promotion without fragmenting Smart Bidding data. Applies a strict three-question filter, skip close variants outright, redirect queries needing a different ad to structure work, and promote only when a query buys real control or visibility (keyword insertion quality, standalone QS diagnostics, auction insight visibility, PMax routing priority, a keyword-level final URL), then adds survivors as exact match by default and cleans up any routing overlap with negatives. Run it monthly per priority ad group, or when candidates arrive from analyze-search-term-reports. It is the promotion executor, not the report scanner (analyze-search-term-reports) nor keyword discovery for new builds (research-keywords); queries needing a different ad route to build-search-campaign-structure instead. --- # Promote Search Terms to Keywords ## Purpose Every query the account matched is a free experiment result, but not every good result deserves keyword status. Promotion buys control (predictable routing, keyword-level URLs, Search-over-PMax priority) and visibility (quality diagnostics, auction insights, trendable history) at the price of fragmenting query data across more entry points. This skill applies a filter strict enough that each promotion pays for itself, then executes with exact match and clean routing. ## When to run - Monthly quick pass over the top queries of each priority ad group. - A candidate list just arrived from `analyze-search-term-reports`. - After promotions or seasonal spikes surface new high-intent phrasings. - Keyword insertion headlines are underperforming because keywords lag how users actually phrase things. - Broad match or expanded matching is discovering strong queries the account should own explicitly. ## When NOT to run - Scanning raw search term reports for irrelevance and candidates → `analyze-search-term-reports` (it feeds this). - Building the keyword universe for a new campaign → `research-keywords` + `cluster-and-map-keywords`. - The query needs a meaningfully different ad → that is an ad-group split, `build-search-campaign-structure` territory (or the split path in `improve-ad-relevance`), not a promotion. - A brand-new ad group under 30 days old, let the report populate first. ## Prerequisites - 30–90 days of search term history for the ad group. - The ad group's current keyword list (duplicate/variant checks). - Ad group confirmed single-theme (one ad honestly covers it), promoting into a muddled group compounds the mess. ## Procedure 1. **Pull candidates.** `gads_get_search_terms_report` for the target ad group, last 30 days (90 for thin volume), sorted by impressions. Apply the volume gate: high-volume accounts ≥100 impressions, mid-volume ≥50, low-volume just the top 10 not-yet-added queries by impressions. Conversions ≥1 is a useful secondary filter, not a requirement, control and visibility benefits exist pre-conversion. 2. **Question 1, is it a close variant of an existing keyword?** Word order flips, singular/plural, filler words, typos, and no-value tack-ons (a bare "online") are variants. Variant → SKIP, even if it converts: the existing keyword already captures that traffic, and a duplicate entry point fragments data while adding nothing. Check against the live keyword list, not memory. 3. **Question 2, would it need a different ad?** If the query's intent demands a different promise, CTA, or offer than the ad group's RSA delivers, promotion is the wrong tool, note it for the ad group that fits, or route to structure work to create one. Same ad but a better-fitting PAGE exists → that is precisely the promote-with-keyword-URL case; continue. 4. **Question 3, does promotion buy at least one concrete advantage?** Promote only if one or more hold: the term reads well as an inserted headline; it deserves standalone quality-component tracking; auction-level competitive visibility on this phrasing matters; explicit keyword status should anchor this query in Search against PMax; a keyword-level final URL routes it to a stronger page; or the team wants its history trendable. Tie-breaker: imagine the term as the inserted headline, visibly better for the user → promote; identical or awkward → skip. Zero advantages → SKIP. Typical promotes: purchase-intent modifiers (buy/sale/discount phrasings), benefit qualifiers (free shipping, free returns), true synonyms users search (attorney for lawyer), offer modifiers (free trial, demo). Typical skips: reorderings, plurals, prepositional rephrasings, typos. 5. **Present the decision table.** Term, verdict, which question decided it, proposed match type and any keyword-level URL. Proceed on user confirmation. 6. **Execute.** After `gads_policy_guardrail` (before the session's first Google Ads write), add survivors to the SAME ad group via `gads_add_keywords`: exact match as the default (phrase only when controlled expansion from the root is wanted; never broad, broad is a discovery layer, and promotion is what you do with its discoveries). Attach a keyword-level final URL where a more specific page converts better under the same ad. Preview first (validate_only default), commit only after explicit user approval. Keep the original keyword active, it remains the catch-all while the promotion owns its specific phrasing. 7. **Clean up routing overlap (edge case).** If a promoted query previously matched through a DIFFERENT ad group, check for dual entry points and, if present, add an exact-match negative in the non-preferred group via `gads_add_negative_keywords` (preview → approval → commit). Same-ad-group promotions rarely need this. 8. **Validate on schedule.** Immediately: keyword active and accruing impressions. Days 7–14: it is capturing its intended queries (re-pull the term report). Days 14–30: `gads_get_keyword_performance`, quality score populated and in line with the ad group average. Red flags: QS clearly below the group average → ad/page mismatch, route to `improve-quality-score`; impressions without conversions where the parent converted → fragmentation without value, propose pausing the promotion. ## Decision rules - **The short version of the filter:** a close variant never gets promoted; a query that deserves different ad copy is a structure task, not a promotion; everything else is promoted only if the new keyword buys concrete control or visibility. - **Volume gates:** ≥100 impressions (high-volume accounts), ≥50 (mid), top-10 rule (low). - **A converting close variant is still a close variant**, conversions do not override Question 1; the parent keyword already banks them. - **Match type: exact by default,** phrase deliberately, broad never. - **Keyword-level URL vs. split:** same ad + better page → keyword URL here; different ad needed → split, not promotion. - **Never delete the parent keyword** after promoting a specific child; they operate as catch-all plus specialist. - **No quota exists.** Some ad groups yield zero promotions in a pass, others five; forcing a number produces fragmentation. - **Low-volume promotes are legal but slow:** QS feedback takes far longer; set expectations accordingly. ## Common failure modes - **Promoting everything that converted.** Most converting terms are close variants; blanket promotion is the fastest route to a fragmented, slow-learning account. - **Word-order and plural promotions**, zero insertion benefit, zero control benefit, pure entry-point duplication. - **Promoting into broad match,** which re-opens discovery on a term you were trying to pin down. - **Forcing a different-intent query into the current ad group** because promotion is easier than a split; QS arrives low and stays low. - **Skipping the keyword-level URL** when a sale query could land on the sale page, the cheapest landing-page win available. - **Fire-and-forget promotions:** without the 7/14/30-day checks, fragmenting promotions linger unnoticed. - **Deleting the parent after promoting the child,** surrendering the catch-all coverage that fed the discovery in the first place. ## What done looks like - Every gated candidate has a recorded verdict and the question that decided it. - Survivors live as exact match in their home ad group, keyword-level URLs attached where a better page existed. - No dual entry points remain, routing negatives cover the rare cross-group overlap. - The 7/14/30-day checks are scheduled, and no red flags stand after the 14-day mark. ## Related skills - Fed by: `analyze-search-term-reports` (candidate lists), `configure-ai-max-for-search` and broad-match discovery (query sources). - Escalation: `build-search-campaign-structure` / `improve-ad-relevance` when Question 2 says split. - Aftercare: `improve-quality-score` for low-QS promotions; `run-n-gram-analysis` for routing/negation cleanup at pattern level. - Orchestrated by: `run-search-campaign-optimization-cycle` (query phase).