Topic research

Topic Research

Turns a topic into a rigorous, sourced, fact-checked report. Two artifacts come out every time: a markdown brief (agent-readable, the handoff to a content-writer skill) and a branded HTML report (human-facing, deployable). The workflow is: interview the user so the research is targeted, fan out parallel research sub-agents across source types, verify every hard claim, synthesize to markdown, render to HTML, deploy.

[!important] The two rules that make this good

1. Targeted, not generic. The Phase 0 Q&A shapes every sub-agent. Research aimed at a purpose beats a topic dump every time.
2. Verify before you publish. No hard number reaches the report without a fact-check verdict and a caveat. Fact and opinion stay visibly separate.

---

Phase 0: Targeted Q&A + capability probe

Do both before any research runs. Ask conversationally, one thing at a time, adapting to answers.

A. Targeted Q&A (this shapes the whole run)

1. Topic, and what they already believe or suspect about it.
2. Purpose: is this to write a specific piece of content (which format? which audience?), to make a decision, to brief a team, to prep for a talk? A content purpose changes what the report emphasizes and how the markdown is structured downstream.
3. Angle / biases / skepticism to reflect: a point of view they want the research to support or pressure-test, claims they are suspicious of, hot takes to stress-test. These become explicit search directives for the sub-agents. If they have none, the research stays neutral and simply reports the tension it finds.
4. Depth: Quick / Standard / Deep (see below).
5. Output: report + markdown always; deploy target is a Claude live artifact (instant, no infra) or Vercel (stable custom URL). Ask which.
6. Brand: default to the neo-brutalist "Signal Report" look in assets/report-template.html. If they have a brand (site, design system, colors/fonts/logo), extract and restyle; the CSS is token-driven at the top of the template.

Capture the answers in a short brief-config (topic, purpose, audience, directives, depth, deploy, brand) that you carry through every phase.

B. Capability probe

Detect which connectors are available (see references/connectors.md for the exact checks and how to connect each): Firecrawl, Apify, a scholarly/PubMed MCP, YouTube MCP / vidIQ, Reddit MCP, browser-harness, and the Vercel deploy path.

Show the user the research plan you will run given what is connected, then offer to connect the high-value missing ones (Firecrawl and Apify are the biggest upgrades; PubMed only matters for medical topics). If they decline, name the fallback each stream will use and continue. Never hard-fail for a missing connector; degrade.

Depth control (user preference + topic-aware)

• Quick: 2-3 streams, shallow read, ~1 fact-check pass. For fast-moving or lightly-researched topics.
• Standard: all 4 streams, ~15 sources, full fact-check. The default.
• Deep: all 4 streams with more agents per stream, wider reading, adversarial fact-check (multiple verifiers per claim).
• Auto-downshift: if a topic has little scholarly literature (true for most marketing topics), lighten or skip the scholarly stream rather than padding it, and say so. Do not fake depth.

---

Phase 1: Parallel research fan-out

Launch one sub-agent per source type, concurrently (send them in a single batch). Give each the topic + purpose + the user's angle/biases as explicit directives. Each returns structured markdown: findings (one source URL each), a "hard claims to verify" list, and vendor/anecdotal claims flagged. Full parameterized prompts are in references/research-agents.md.

Stream	Job	Primary connector	Fallback ladder
Scholarly / evidence	Credible papers, studies, citations only. Domain-aware: medical → PubMed/PMC (+ bioRxiv/medRxiv, ClinicalTrials); AI/CS → arXiv; general → Semantic Scholar / Scholar	Scholarly/PubMed MCP + Firecrawl paper index	web search on journal / .edu / .gov domains → browser-use
Forums / community	Real language, pain points, firsthand results (anecdotal), objections	Apify Reddit scraper	Reddit MCP → web search site:reddit.com + fetch → browser-use
Web / vendor	Vendor docs, industry data, reputable blogs, the tool/landscape	Firecrawl search + scrape	web search + web fetch → browser-use for JS-heavy pages
Creators / video	What top creators teach; recurring tactics + contrarian takes	YouTube MCP + vidIQ + transcripts (yt-dlp / watch)	Apify YouTube scraper → web search for summaries

Keep per-stream reading within the depth budget and have each agent log/report anything it deliberately skipped. No silent truncation.

---

Phase 2: Fact-check pass

Collect every "hard claim" from all streams, dedupe, and verify with the fact-checker skill (Standard: one pass; Deep: multiple independent verifiers per claim, kill on majority-refute). Each claim gets a verdict (VERIFIED / PARTIAL / PROJECTION / VENDOR-CLAIM / ANECDOTAL / FALSE), a primary source, and a one-line caveat. Apply corrections to the synthesis. A caught correction is a feature: surface it in the ledger.

Never fact-check firsthand forum anecdotes as fact; they are sentiment and stay labelled as such.

---

Phase 3: Synthesize to the markdown brief

Merge the four streams + verdicts into one structured markdown brief using references/brief-template.md: TL;DR, headline stats, verified evidence, a "what the evidence says" / playbook section (tag each point with how many source types corroborate it), the counter-narrative / skepticism, a tool-or-landscape section where relevant, voice-of-market language, the claims-verified ledger, and grouped sources. Keep fact and opinion visibly separate, and reflect the user's stated angle honestly (support it where the evidence does, push back where it doesn't).

[!important] The markdown is the point, not a waypoint Produce the markdown before the HTML and always keep it. It is the agent-readable handoff: the next skill in the chain (a brand-voice content writer) consumes this exact file to write the piece. HTML is the human render; markdown is the machine brief. Save it as <topic-slug>-brief.md in the working folder.

---

Phase 4: Render to the branded HTML report

Adapt assets/report-template.html (a complete worked example, the GEO/AEO "Signal Report"). Keep the <style> block and the component patterns (KPI cards, evidence cards, playbook cards, skeptic quote blocks, the tool table, the claims-ledger rows, grouped sources) and swap in the new topic's content from the markdown brief. Restyle the CSS tokens + brand-badge text if the user gave a brand. The file must stay self-contained (no external assets except the Google Fonts link already in the template). Verify it renders (open it, check computed styles / console) before deploying.

---

Phase 5: Deploy and deliver

Deploying makes the report public, so confirm first: show the user the rendered report and the fact-check ledger, and get an explicit go-ahead before deploying. If they want changes, revise and re-confirm.

Deploy to the target chosen at intake (see references/connectors.md for both paths):

• Claude live artifact: instant, no infrastructure, good default for one-off research.
• Vercel: stable custom URL. Locally the CLI is fine; from a cloud routine, git push is the deploy (never the Vercel CLI/API).

Save the markdown + HTML locally, return the live URL, and tell the user the markdown path plus the one line that matters: this brief can feed straight into a content-writer skill to draft the piece.

---

Principles (baked into every run)

• Connector-adaptive with graceful degradation and ask-to-connect. Never hard-fail.
• Every claim carries a source. Verify hard numbers before publishing. Label vendor / anecdotal / projection.
• Triangulate across source types and show the corroboration count. One source alone lies.
• Cap depth for cost; log anything skipped.
• Targeted beats generic: the Q&A directives ride along into every sub-agent.
• Two artifacts, always: markdown brief (handoff) + HTML report (render).

Reference files

• references/research-agents.md: the parameterized sub-agent prompts (4 research streams + fact-check).
• references/connectors.md: capability probe, how to connect each source, fallback ladders, and both deploy paths.
• references/brief-template.md: the markdown brief skeleton (the handoff artifact structure).
• assets/report-template.html: the branded "Signal Report" HTML, a complete worked example to adapt.

Self-improvement

This skill is never finished. Improve it as you use it.

• When the user corrects how a step was done, update the relevant reference file (research-agents.md, connectors.md, or brief-template.md) or this SKILL.md so the correction sticks. Do not just fix it for this run.
• When a correction is a hard rule ("always X", "never Y"), add it as a permanent rule here.
• When the user says a brief or report was genuinely good, save it to references/examples/ so it becomes a model for future runs.
• Keep the skill small: when you add something, run the deletion test and cut anything that no longer changes behavior.