Research

Research Skill

Produce a research dossier that ends in a beat spec — a quantified statement of what this article must do to deserve the top of this SERP. The outline is bound by the beat spec; the quality gate scores against it. If the research is thin, everything downstream is thin: this is the most leverage-dense stage of the pipeline.

Tool calls: read references/semrush-mcp-cheatsheet.md first — it pins the REAL tool/report names and parameter shapes (the only pattern is get_report_schema → execute_report). Never call mcp__semrush__keyword-overview, topic-research, serp-results or other invented names; they don't exist.

Input

A target keyword as a string. Example: ai girlfriend app.

If invoked with no argument, read the most recent context file in content-pipeline/0-context/ and prompt the user for the keyword.

Process

1. Slugify. python scripts/slugify.py "<keyword>"; store the slug.

2. Read brand context. brand-config.md — audience, products, voice. Research framing should consider what this brand can credibly own.

3. Pull keyword data via Semrush MCP (cheatsheet steps 1–4):

   • phrase_this + phrase_kdi → volume, CPC, competition, KD%
   • phrase_fullsearch + phrase_related (limit 40–50) → variation pool; keep 10–15 same-intent keywords with volumes
   • phrase_questions (limit 30–40) → group into 3–5 question themes; drop spam
   • phrase_organic (limit 10–20) → the ranking URLs, in order

4. Build the SERP benchmark (MANDATORY — the heart of this skill). Extract the full content of the top 5–8 ranking pages (skip ads, skip our own domain): for each page, POST to Firecrawl (https://api.firecrawl.dev/v1/scrape, body {"url": <url>, "formats": ["markdown"]}, header Authorization: Bearer $FIRECRAWL_API_KEY); fall back to WebFetch on error. From each extraction record:

   • Word count (of article body, excluding nav/boilerplate — estimate honestly)
   • Title + full H2/H3 list
   • Format (guide / listicle / comparison / how-to / explainer) and item count if list-shaped ("9 apps reviewed")
   • Evidence types used: tables (count them), screenshots/images (count), original data, expert quotes, hands-on detail
   • What it does well; where it's thin or generic Then compute the benchmark table:
   • Median + max word count of the top 3
   • Modal format and item-count range
   • Table/visual usage across the SERP ("4 of 5 pages have a comparison table")
   • Consensus topics — covered by 3+ of the extracted pages (the article MUST cover all of these)
   • Partial topics — covered by 1–2 (differentiate with more depth)
   • Gaps — asked by searchers (question themes, deep research) but covered by nobody (the information-gain opportunity)

5. Authority check. domain_ranks for the top-3 domains, url_organic (limit 10) for the top-3 URLs → is this SERP beatable, and what secondary keywords do winning pages also rank for (fold the good ones into the outline's subtopics).

6. Deep web research via OpenRouter (Perplexity). Voice-of-customer + community signals (Reddit, forums, review sites):

   doppler run -- python .claude/skills/research/scripts/openrouter_research.py \
     --keyword "<keyword>" --slug "<slug>"
   

   Output lands at content-pipeline/1-research/{slug}-deep.md. If OPENROUTER_API_KEY_BLOG_AGENT isn't set, skip and note it in the dossier — don't fail the pipeline.

7. Recommend an angle. One-sentence thesis that wins against the current SERP, with justification grounded in the benchmark's gaps + what this brand can credibly demonstrate first-hand.

8. Write the beat spec — the dossier's final section, in exactly this shape:

   ## BEAT SPEC (binding on outline + quality gate)
   - Target word count: <max(1.1 × median of top 3, 1800)> (±20%)
   - Format: <modal SERP format>; item count: <max items on SERP + 1, if list-shaped>
   - Comparison table: <required iff ≥2 of top 5 have one — list required columns>
   - Must-cover topics (consensus): <bulleted list — every one becomes outline coverage>
   - Differentiation topics: <partial-coverage topics we go deeper on>
   - Information gain (≥1 REQUIRED): <the thing nobody on page 1 has — original comparison, first-hand product walkthrough, fresh data, better explanation>
   - Secondary keywords to work in naturally: <from url_organic + variations>
   - Beatability: <honest read — authority spread, content quality of incumbents>
   

9. Write the dossier to content-pipeline/1-research/{slug}.md per templates/research-template.md. No {{VAR}} markers left. Include a "Deep web research findings" summary section (the -deep.md file stays available to /draft).

10. Emit chartable data (unchanged): if the dossier surfaces numeric breakdowns worth charting, write content-pipeline/1-research/{slug}-data.json ({label: number} dicts, snake_case keys, _meta.source for auditability). Don't fabricate; omit if nothing chartable.

Output

content-pipeline/1-research/{slug}.md — 1,200–2,500 words. Dense, scannable, no fluff. The outline skill reads it end-to-end.

Quality checklist

Before saving, verify:

• Primary keyword has volume, KD%, CPC (real Semrush numbers, not guesses)
• 10–15 same-intent related keywords with volumes
• 10+ questions grouped into 3+ themes
• Top 5+ pages extracted with word count, H2 list, format, item count, table/visual counts
• Benchmark table computed (median/max words, modal format, table usage)
• Consensus / partial / gap topics explicitly listed
• BEAT SPEC section present, complete, and numerically specific
• One-sentence recommended angle with justification
• Deep-research section present (or explicit note that OpenRouter wasn't configured)
• At least 3 verbatim user quotes when deep research ran
• No raw CSV/JSON dumps; everything synthesized
• Brand context reflected — the angle is something THIS brand can credibly own

When to re-run

If the SERP shifts (new competitor, format change) or the angle stops holding. Re-running here is cheaper than reworking any later stage.