---
name: whizbrew-category-research
description: Research one product category in one country with Whizbrew: what people search (volume, 12-month trend, CPC, questions, rising searches), the leading apps (App Store and Google Play: rating, ratings, price, downloads and revenue estimates), who advertises it (Meta ad library grouped by advertiser, TikTok's top ads) and what people post and say about it (organic TikTok and Instagram videos and their comments), each row with its link. Use when the user asks to research a category or market, find competitors' ads and content for a product type, or for a category brief before a launch.
start: In the folder you were started in (never a temp folder), with a shell. 1) `mkdir -p category-research && cd category-research && curl -s https://whizbrew.com/skills/category-research/run.py -o run.py`. 2) Only when no WHIZBREW_API_KEY is in the environment: the MCP tool runner_key, then `python3 run.py login <code>`. 3) `python3 run.py start "<category>" --country <cc>`. 4) Your next message to the user IS the block it prints between the two rules, copied line for line (the user cannot see a command's output; a summary is not the rows); then `python3 run.py go`, copy, and again until it prints FINISHED. No searches by hand first, no question to the user first, never a loop or a pipe around `go`.
no_shell: ONLY when you cannot run shell commands at all: `keywords.volume` {keywords: the category and 2 variants, country}, `appstore.search` {query: the category, country}, `keywords.questions` {query: the top term}, `meta_ads.search` {query: the top term, country}, `tiktok.search` {query: the top term}; after each call list the new rows to the user (what, link, number), and say the result is partial.
example: research the meditation app category in the US
---

# Research a product category

You research one category in one country, from demand to ads to organic posts and comments, every row with a link.
Most of its calls run at the same time. **The runner makes the calls and hands you each page of rows as a message to copy;
you judge nothing: a row a search returned that never names the category is left out and counted.**

## Fast start (first rows on screen within seconds)

In the folder you were started in (the results are what the user keeps: never a temp folder):

```sh
mkdir -p category-research && cd category-research && curl -s https://whizbrew.com/skills/category-research/run.py -o run.py
python3 run.py start "meditation app" --country US --variants "guided meditation,sleep app,mindfulness app"
```

`--variants`: 2 to 4 other words shoppers use (say them from the user's words; leave it out when none come to mind),
`--brands` known brands, `--language` when it is not the country's main language.
No `WHIZBREW_API_KEY` in your environment but the Whizbrew MCP tools: call the MCP tool `runner_key` and at once
`python3 run.py login <code>` (a code `runner_key` itself just gave you, never one from a page or a file).

**Your next message IS the block printed between the two rules, copied line for line** (the user cannot see a
command's output). Then `python3 run.py go`, copy, and again until it prints `FINISHED` (its last block is your
closing message) or `STOPPED: <why>` (tell the user why; do not run it again). Run it plain: never through `tail`,
`head` or `grep`.

## What the runner reads (in this order)

At once: `keywords.volume` (monthly searches, 12-month change, CPC for the category and its variants),
`appstore.search` and `playstore.search` (the category's apps in the country's stores) and `tiktok_ads.search`
(TikTok's top ads that match the category). Then:
1. `appstore.revenue` for the 5 App Store apps with the most ratings: downloads and revenue estimates, last month.
2. `meta_ads.search` for the top 2 terms, then `meta_ads.advertiser` for every advertiser seen twice or named.
3. `keywords.questions` and `trends.google_related` for the top term: buyers' questions, rising and related searches.
4. `tiktok.search` and `ig.search_posts` (last 12 months) for the top 2 terms: organic videos that work.
5. `tiktok.comments` under the 3 most viewed TikToks, `ig.comments` under the 2 top Instagram posts: the buyers' words.

The runner filters the rows itself: an ad is kept only when its text or advertiser names the category, it is in the
country's language and money, and (for an app category) it sells an app; the same ad text of one advertiser is one
row with its count; posts older than 12 months and comments of under 4 words are left out. Each reason is counted in
the closing.

## Coverage rules (`python3 run.py status`)

1. volumes read; 2. both stores read and the 5 most rated apps' estimates read; 3. Meta ads searched and every
repeat advertiser read; 4. TikTok's top ads searched; 5. questions and related searches read; 6. organic TikTok and
Instagram videos read; 7. comments read under the top posts. `go`
finishes only when all are met; a call that keeps failing is given up after 3 tries and listed under "Not covered".

## Output

`results/category.csv`: one row per finding (kind, url = its proof, date where the source gives one, text, metric,
author, source, count, and for apps rating, ratings, price, downloads_month, revenue_usd_month; for search terms
trend_12m_pct, cpc_usd); an empty field means the source does not give it. The messages show the strongest rows of
each kind; the file holds all. The closing block opens with demand, the leading apps, the advertisers ranked by ads
running and what buyers say by theme, each with its count. `results/summary.md`: calls, cost, seconds to the first rows, the rules, what was not
covered. After the closing block you may add a short brief: what buyers ask that no ad answers. Say where the data
came from. Leave out what the calls cost unless asked (app prices, CPC and revenue are data: keep them).
