---
name: cluster-and-map-keywords
description: >-
  The bridge between keyword research and campaign build: takes a raw researched keyword list and produces
  named clusters that each pass a one-ad coverage test, ranked into launch tiers, tagged with dominant search
  intent, and mapped to a landing page (or flagged as blocked when no suitable page exists). Filters the list
  first with a keep/hold/drop relevance pass and banks the dropped terms as future negatives. Use it whenever a
  fresh keyword list needs organizing before structure work, new campaign, restructure, or new product line.
  Upstream discovery belongs to research-keywords; downstream assembly belongs to build-search-campaign-structure;
  ongoing single-term promotion from live traffic is promote-search-terms-to-keywords, not this.
---
# Cluster Keywords and Map Landing Pages

## Purpose
A raw keyword list is not a campaign plan. This skill filters it for relevance, groups survivors into clusters that
one ad could honestly serve, ranks the clusters by business impact so launch order is explicit, labels each with its
dominant intent, and pins each to a landing page. Every cluster that leaves this skill is one future ad group with
one creative theme and one destination, and the rejects become the seed of the negative keyword system.

## When to run
- A completed keyword research list (with volume, competition, CPC data) is ready to be organized.
- A new Search campaign is being planned from scratch.
- An existing campaign is being restructured around fresh keyword data.
- A new product or service line needs its own keyword architecture.

## When NOT to run
- No keyword list yet → `research-keywords` first (this skill organizes, it does not discover).
- Structure is ready to build in the account → `build-search-campaign-structure`.
- You are harvesting individual queries from a live account → `promote-search-terms-to-keywords`.
- Writing the ads for finished clusters → `write-compelling-rsas`.

## Prerequisites
- The researched keyword list with per-keyword volume, competition, and CPC estimate (from `research-keywords`;
  gaps can be backfilled here via forecast tools).
- Business offering details: products, services, pricing tiers, geographies served.
- An inventory of existing landing pages with URLs and their primary topic.
- Target CPA or ROAS, to judge CPC viability during prioritization.

## Procedure
1. **Assemble the worksheet.** One row per keyword: term, volume, competition, CPC, then empty columns for
   relevance verdict, cluster, intent, and landing page. If volume or CPC is missing for any rows, backfill via
   `gads_keyword_ideas` (historical metrics for supplied keywords) or `gads_keyword_forecast`.
2. **Relevance pass, keep / hold / drop.** Judge every keyword:
   - DROP: describes something the business does not sell, a geography it does not serve, another industry's use
     case, or pure research intent with no conversion path.
   - KEEP: names what the business sells, a problem it solves, carries commercial/transactional modifiers, or
     matches an existing page topic.
   - HOLD: adjacent offering, uncertain audience, viable but tiny volume, or roadmap-dependent.
   This is an LLM judgment call with user confirmation on anything genuinely ambiguous.
3. **Resolve the holds.** For each HOLD keyword ask one question: if someone searched this, could the business
   serve a relevant page and fulfill the intent? Yes → keep; no → drop; still unsure → leave flagged for the
   business owner, capped at 10–15% of the total list. More than that means the business scope itself is unclear, stop and ask.
4. **Bank the drops.** Move every dropped keyword to a negatives sheet with its drop reason. Do not discard them:
   this sheet feeds the shared irrelevant-terms list during `build-search-campaign-structure`.
5. **Cluster by one-ad coverage.** Group the keeps so that within each cluster, a single RSA's headlines and one
   landing page would fit every member. Merge synonyms, close variants, word-order flips, and equivalent modifiers
   into the same cluster (match types absorb those differences). If any member would demand a different promise,
   CTA, or page, it starts a new cluster. Name each cluster after its creative theme, the name becomes the ad
   group name downstream.
6. **Sanity-check cluster sizes.** 4–20 keywords is the healthy band. 1–3 members → try merging with a neighbor if
   coverage still holds. 21+ → hunt for a hidden sub-theme worth its own ad. Size is a signal, not a rule: two
   high-volume keywords that need their own creative theme are a legitimate cluster.
7. **Score and tier the clusters.** For each cluster, aggregate monthly volume, average competition, average CPC
   against the allowed CPC implied by target CPA × expected CVR, share of buying-intent terms, and the margin of
   the product it maps to (`gads_keyword_forecast` can pressure-test expected volume and cost). Rank into three
   tiers: Tier 1 launch-first (volume + intent + viable CPC + margin), Tier 2 launch after Tier 1 stabilizes,
   Tier 3 backlog/seasonal. One-line rationale per cluster.
8. **Label dominant intent.** Tag each cluster transactional, commercial-investigation, informational, or
   navigational using its members' signal words (buy/pricing/hire → transactional; best/vs/review → commercial;
   how/what/guide → informational; brand names → navigational). Mixed clusters take the majority label; an even
   split takes the higher-intent label. `gads_keyword_themes` can cross-check the thematic grouping.
9. **Interrogate informational clusters.** Each one stays only with a complete path: ad message that fits a
   learner, a page that fulfills the question, and a real conversion mechanism (guide, tool, consultation). No
   path → Tier 3 or delete. Paid clicks on unanswerable questions are the quietest waste in Search.
10. **Map landing pages.** Match each cluster to the best existing page: topic directly addresses the cluster,
    a visible conversion action exists, page loads correctly (page inspection is a HUMAN STEP outside VigilDog).
    Optionally run `gads_run_gaql_query` against existing ads/keywords to see which final URLs the account already
    uses per theme. No suitable page → mark the cluster BLOCKED with a one-paragraph brief of the page it needs
    (topic, offer, conversion action); blocked clusters do not get built.
11. **Deliver the cluster sheet.** Final worksheet: cluster → members, tier + rationale, intent label, landing
    page or BLOCKED brief, plus the banked negatives sheet and the unresolved-hold list. Optionally sketch the
    downstream shape with `gads_plan_search_campaign` using Tier 1 clusters. This artifact is the direct input to
    `build-search-campaign-structure`.

## Decision rules
- **The grouping test is ad coverage, not topical similarity:** same cluster only if one ad and one page honestly
  serve every member.
- **Relevance before grouping, always.** Clustering an unfiltered list pollutes every downstream decision.
- **Hold cap:** unresolved holds above 10–15% of the list = scope problem, escalate to the business owner.
- **Tier 1 requires all four:** meaningful volume, buying-leaning intent, CPC the unit economics can carry, and a
  product margin worth the traffic. Missing one → Tier 2. Missing several or speculative → Tier 3.
- **Intent tie-break** goes to the higher-commitment label (transactional > commercial > informational).
- **Informational survival test:** matching message + fulfilling page + conversion mechanism, all three or out.
- **Blocked beats botched:** a cluster without a fitting page waits for the page; it never launches against the
  homepage.

## Common failure modes
- **Topic-clustering.** "Everything about running shoes" fails coverage the moment trail, sale, and kids' terms
  need different promises. Test pairs against the one-ad question.
- **Confetti clusters.** Splitting singular/plural or word-order variants into separate clusters creates dozens of
  starving ad groups; variants share a cluster by definition.
- **Skipping the relevance pass.** Ten minutes saved, weeks of polluted structure and wasted spend later.
- **Deleting the drops.** The rejects are half the value, they are the negative list you otherwise rebuild from
  live waste.
- **Informational keywords by default.** They inflate volume projections and quietly never convert without a
  designed path.
- **Launching all tiers at once.** Tier 1 exists to concentrate budget where learning is fastest; everything-day-one
  splits data thin everywhere.
- **Homepage fallback.** The mapping step's whole point is admitting when a page does not exist yet.

- **Letting cluster names drift from creative themes.** The name becomes the ad group name and the shorthand every
  later review uses; a vague name ("Misc terms 2") guarantees the theme blurs during the build.
- **Scoring tiers on volume alone.** A huge cluster with CPCs the margin cannot carry is a Tier 3 trap dressed as
  a Tier 1 opportunity; all four tier criteria carry weight.

## Related skills
- Run before: `research-keywords` (produces the input list).
- Run after: `build-search-campaign-structure` (consumes the clusters), then `write-compelling-rsas`.
- Parallel/lifecycle: `promote-search-terms-to-keywords` for ongoing single-query additions once live;
  landing-page gaps route to `build-a-high-converting-landing-page`.