# Keyword Research

Discover and cluster keywords with intent and difficulty signals pulled from the live web into a saved file.

## When to use

- A content or SEO (search engine optimization) plan needs a fresh list of target keywords for a topic, product, or competitor space.
- You need to expand a seed keyword into related terms, questions, and long-tail variants grouped by intent.
- Someone asks for a content calendar or brief and there is no existing keyword research file to build from.

## Tools

- `browser-search`: run SERP (search engine results page) queries against seed keywords and topic phrases to surface related searches, autocomplete-style suggestions, and competing pages.
- `browser-navigate`: open the search result pages, competitor articles, and keyword-tool pages returned by search.
- `browser-extract`: pull the visible keyword lists, "people also ask" questions, related searches, headings, and on-page copy from the pages you navigate to.
- `write-file`: save the clustered keyword list, with intent and difficulty notes, to a file for downstream content work.

## Playbook

1. Confirm the seed topic, target audience, and any exclusions with the task details before starting.
2. Run an initial query for the seed keyword using `browser-search` to see the current SERP landscape.
3. Use `browser-navigate` to open the top-ranking pages and any "related searches" or question panels shown in the results.
4. Use `browser-extract` on each opened page to capture headings, question phrasing, and repeated terms that signal related keywords.
5. Repeat `browser-search` for 3-5 keyword variants (synonyms, "how to", "best", "vs", buyer-intent phrases) to widen coverage.
6. Group the collected terms into clusters by intent (informational, commercial, navigational, transactional) and note apparent difficulty based on how many high-authority pages dominate each SERP.
7. Draft the final table (keyword, cluster, intent, estimated difficulty, source URL) as markdown or CSV text.
8. Save the draft with `write-file` to a clearly named keyword-research file.
9. Summarize the cluster count and top opportunities when completing the task.

## Failure modes

- Search results return 401/403 or a blocked/consent page: treat as a dead end for that query, note it, and continue with the next seed term via `browser-search`.
- `browser-extract` returns an empty or near-empty result: re-check you navigated to the right URL and that the page finished loading before extracting; retry once.
- Rate limited or repeatedly blocked by a search engine: back off, reduce query frequency, and record the limitation via `update-memory` so future runs know to pace themselves.
- A results page layout has changed and expected sections (e.g., related searches) are missing: fall back to plain `browser-search` queries on narrower phrasing instead of relying on page structure.

## Done when

- A keyword-research file exists (via `write-file`) containing clustered keywords with intent and difficulty notes.
- Each cluster has at least one supporting source URL captured during research.
- The task is completed with a summary of top clusters and recommended priority terms.