content-research-brief

What this skill does

# Content Research Brief

Research a topic by collecting 5-10 real source articles, auto-tagging them by theme,
extracting key data points, and synthesizing unique content angles. The output is a
structured research brief that any downstream content skill can consume.

**The problem this solves:** Most AI-written affiliate content is generic because it's
written from the model's training data — not from real, current sources. This skill
forces research-first content creation: find real articles, extract real data, then
write from those sources. The result is content with specific stats, real quotes, and
current information that readers (and Google) actually value.

Inspired by the [content-pipeline](https://github.com/Affitor/content-pipeline) approach:
Topic → Search → Select sources → Synthesize → Write with context.

## Stage

This skill belongs to Stage S2: Content — but acts as the research foundation for all content skills.

## When to Use

- Before writing any article, blog post, or long-form content
- When you need current data and stats about a topic (not just AI-generated claims)
- When creating comparison content (need real feature/pricing data from sources)
- When writing about a product launch, funding round, or industry trend
- After `trending-content-scout` identifies a topic — research it deeper
- When you want unique angles: N sources → N different content pieces

## Input Schema

```yaml
topic: string                  # (required) "HeyGen AI video tool", "email marketing trends 2024"
source_count: number           # (optional, default: 7) How many sources to collect (3-10)
source_types: string[]         # (optional, default: ["news", "blog"])
                               # Options: "news" | "blog" | "linkedin" | "youtube" | "reddit" | "academic"
freshness: string              # (optional, default: "month") "day" | "week" | "month" | "year" | "any"
product: object                # (optional) Focus research on a specific product
  name: string                 # "HeyGen"
  url: string                  # "https://heygen.com"
language: string               # (optional, default: "en") "en" | "vi" | any ISO 639-1 code
angle_count: number            # (optional, default: 3) How many unique content angles to generate
```

## Workflow

### Step 1: Search for Sources

Execute multiple searches to find diverse, high-quality sources:

```
Primary search:
  web_search "[topic]" → top results
  
Source-type-specific searches:
  IF "news" in source_types:
    web_search "[topic] news [current year]" → recent news articles
  IF "blog" in source_types:
    web_search "[topic] blog review analysis" → in-depth blog posts
  IF "linkedin" in source_types:
    web_search "[topic] site:linkedin.com" → LinkedIn posts/articles
  IF "youtube" in source_types:
    web_search "[topic] site:youtube.com" → YouTube videos with descriptions
  IF "reddit" in source_types:
    web_search "[topic] site:reddit.com" → Reddit discussions with real user opinions
  IF "academic" in source_types:
    web_search "[topic] research study data statistics" → data-heavy sources

Product-specific (if product provided):
  web_search "[product.name] review [current year]"
  web_search "[product.name] alternatives comparison"
  web_search "[product.name] pricing features"
  web_search "[product.name] news launch update"
```

Collect 15-20 search results, then filter down to `source_count` best sources.

### Step 2: Fetch and Extract Source Content

For each selected source:
1. `web_fetch [url]` → extract full article text
2. If fetch fails (paywall, timeout) → use search snippet as summary, note limitation
3. Extract from each source:
   - **Title** and **URL**
   - **Published date** (if available)
   - **Key data points**: stats, numbers, percentages, dollar amounts
   - **Key quotes**: noteworthy statements from experts or users
   - **Main argument/thesis**: what is this source's core message?
   - **Unique information**: what does this source have that others don't?

### Step 3: Auto-Tag Sources

Tag each source with 1-3 theme tags:

| Tag | Trigger Keywords |
|-----|-----------------|
| **AI** | artificial intelligence, machine learning, GPT, neural, model |
| **Funding** | raised, funding, series A/B/C, investment, valuation, IPO |
| **SaaS** | software, subscription, platform, B2B, enterprise |
| **Tools** | tool, app, feature, integration, API, plugin |
| **Trends** | trend, growing, emerging, future, prediction, forecast |
| **Startup** | startup, founder, launch, early-stage, bootstrapped |
| **Growth** | revenue, ARR, users, growth, scale, market share |
| **Industry** | market, industry, sector, regulation, compliance |
| **Pricing** | pricing, cost, free tier, discount, plan, subscription |
| **Comparison** | vs, versus, alternative, compare, switch, migrate |
| **Tutorial** | how to, guide, step-by-step, tutorial, walkthrough |
| **Opinion** | I think, in my experience, hot take, unpopular opinion |

### Step 4: Extract Key Data Points

From all sources combined, extract a master list of:

**Stats & Numbers:**
- Revenue/valuation figures
- User counts / growth rates
- Market size data
- Performance metrics
- Pricing data points

**Quotes & Insights:**
- Expert opinions
- User testimonials (from Reddit, reviews)
- Founder/CEO statements
- Analyst predictions

**Facts & Features:**
- Product features mentioned across multiple sources
- Recent updates/launches
- Integration ecosystem
- Competitive positioning

### Step 5: Synthesize Unique Angles

From the collected sources, generate `angle_count` unique content angles.

**Angle generation rules:**
1. Each angle must use a DIFFERENT primary source as its foundation
2. All angles use ALL sources as context (richer data)
3. Each angle must have a distinct hook and perspective
4. At least one angle should be contrarian or non-obvious

**For each angle:**
```yaml
Angle:
  title: string                # Specific, could be a headline
  primary_source: string       # Which source drives this angle
  hook: string                 # Opening line
  key_data: string[]           # 2-3 data points from sources that support this angle
  format_suggestion: string    # "linkedin_post" | "blog_article" | "tiktok_script" | "twitter_thread"
  unique_value: string         # What makes this angle different from generic AI-written content
```

### Step 6: Compile Research Brief

Organize everything into a structured brief that downstream skills can consume.

### Step 7: Self-Validation

Before presenting output, verify:

- [ ] All sources are real URLs (not hallucinated)
- [ ] Data points are attributed to specific sources
- [ ] At least 3 sources were successfully fetched (not just search snippets)
- [ ] Angles are genuinely different from each other (not rephrased versions)
- [ ] Tags accurately reflect source content
- [ ] Brief includes both positive and critical/balanced perspectives

If any check fails, fix before delivering. Do not flag checklist to user.

## Output Schema

```yaml
output_schema_version: "1.0.0"
topic: string
sources_collected: number
sources_fetched: number                # how many were fully fetched vs snippet-only
sources:
  - title: string
    url: string
    published_date: string | null
    tags: string[]                     # ["AI", "Tools", "Pricing"]
    key_data_points: string[]          # extracted stats and numbers
    key_quotes: string[]               # notable quotes
    main_thesis: string                # 1-sentence summary
    unique_info: string                # what's unique about this source
    fetch_status: "full" | "snippet"   # transparency
master_data:
  stats: string[]                      # all stats across all sources, deduplicated
  quotes: string[]                     # all notable quotes
  facts: string[]                      # key facts and features
  timeline: string[]                   # chronological events if applicable
angles:
  - title: string
    primary_source: string
    ho