Topic Researcher

interface TopicResearcherInput {
  tenantId:    string;
  campaignId:  string;
 
  // Client content context
  industry:          string;    // e.g. "B2B SaaS", "Home Services", "E-commerce"
  niche:             string;    // more specific, e.g. "project management software for construction"
  targetAudience:    string;    // e.g. "marketing managers at mid-market B2B companies"
  contentGoals:      string[];  // e.g. ["drive organic traffic", "generate leads", "build authority"]
 
  // Recent history — the agent avoids duplicating these
  recentTopics: {
    title:       string;
    publishedAt: string;   // ISO date
  }[];
 
  // Temporal context for trend relevance
  currentMonth: string;   // e.g. "April 2026"
  currentSeason: 'spring' | 'summer' | 'autumn' | 'winter';
  hemisphere:   'northern' | 'southern';
 
  // Optional constraints
  preferredAngles?: string[];   // e.g. ["how-to", "listicle", "case study", "opinion"]
  excludeTopics?:   string[];   // topics the client has explicitly asked to avoid
  topicCount?:      number;     // default 12; range 10–15
}

interface TopicResearcherOutput {
  generatedAt:  string;
  topicCount:   number;
  topics:       TopicIdea[];
}
 
interface TopicIdea {
  rank:          number;         // 1 = highest priority recommendation
  workingTitle:  string;         // specific, publication-ready working title
  angle:         string;         // the unique hook or perspective — what makes this different
  relevanceNow:  string;         // why this topic is worth covering now (trend/seasonal/evergreen)
  searchIntent:  'informational' | 'commercial' | 'navigational' | 'transactional';
  evergreen:     boolean;        // true if topic has long-term relevance regardless of timing
  difficulty:    'easy' | 'medium' | 'hard';   // how much research/expertise is required
  difficultyRationale: string;   // one sentence explaining the difficulty rating
  suggestedFormat:  'how-to guide' | 'listicle' | 'case study' | 'opinion/thought leadership' | 'comparison' | 'interview' | 'news analysis';
  estimatedWordCount: number;    // suggested target word count for the format
  competitorGap:  boolean;       // true if RAG found this topic absent from competitor content
  notes:          string;        // anything the content team should know before committing to this topic
}

## Topic Ideas — April 2026 | B2B SaaS / Project Management
 
---
 
### 1. "Why Your Project Management Software Is Making Your Team Slower (And How to Fix It)"
**Angle:** Contrarian take — most software adoption content is positive. This piece addresses the
friction points that arise after 6 months of use, speaking directly to the "we bought the tool but
adoption is struggling" pain point.
**Relevant now:** Evergreen, but spring is a common time for quarterly tool reviews and process resets.
**Search intent:** Informational
**Format:** How-to guide with problem/solution structure | ~2,000 words
**Difficulty:** Medium — requires specific examples of friction points; can be supported with user
research data or survey stats. No proprietary knowledge required.
**Competitor gap:** Yes — top 3 ranking articles are all vendor-produced and promotional in tone.
A neutral, critical angle creates clear differentiation.
 
---
 
### 2. "Construction Project Management Software Comparison: 2026 Buyer's Guide"
**Angle:** Segment-specific comparison targeting the construction niche rather than generic PM software.
**Relevant now:** Commercial intent; buyers research this year-round but activity increases in Q2
when new construction seasons begin.
**Search intent:** Commercial
**Format:** Comparison / buyer's guide | ~3,500 words
**Difficulty:** Hard — requires hands-on familiarity with 4–5 competing products and current pricing.
Requires significant research time and regular updates as products evolve.
**Competitor gap:** No — two direct competitors have comprehensive comparison pages. Needs a
differentiated angle (e.g. focus on integrations with construction-specific tools like Procore).

You are a content strategist generating blog topic ideas for a digital marketing agency client.
Your job is to produce a ranked list of specific, compelling blog topic ideas that are:
- Not already covered in the client's recent content
- Aligned with the client's audience and content goals
- Timely, trending, or evergreen with strong search potential
- Differentiated from what competitors are already covering

CLIENT CONTEXT:
{{CLIENT_CONTEXT}}

KNOWLEDGE BASE CONTEXT:
{{RAG_CONTEXT}}

You have been provided with:
- The client's industry, niche, and target audience
- A list of recently published blog topics to avoid repeating
- Current month and season for temporal relevance
- Web search results showing current trends in the niche
- Competitor content gaps identified from the knowledge base

Generate {{TOPIC_COUNT}} topic ideas. For each topic:
1. Write a specific, compelling working title — not a vague description
2. Identify the unique angle or hook that makes this piece worth reading
3. Explain why it's relevant now (seasonal, trending, or why it's a strong evergreen pick)
4. Classify the search intent: informational, commercial, navigational, or transactional
5. Rate research difficulty: easy (publicly available info), medium (requires synthesis),
   hard (requires expert interviews, proprietary data, or deep expertise)
6. Flag if this is a competitor gap — a topic competitors rank for that the client lacks

Rules:
- No topic should duplicate or closely resemble a topic in the recent-topics list
- Working titles must be specific enough to brief a writer immediately
- Rank topics with competitor gaps and commercial intent higher
- Include at least 2 evergreen topics and at least 2 timely/seasonal topics
- Do not suggest topics outside the client's stated niche or audience

Output as valid JSON matching the TopicResearcherOutput schema.

# Content Topic Framework
 
## What Makes a Good Blog Topic
 
A good blog topic has at least two of the following:
1. **Search demand** — people are actively searching for this information
2. **Business relevance** — it attracts the target audience at the right stage of their journey
3. **Differentiation** — the client can cover it better or differently than what already ranks
4. **Timeliness** — it's trending now, or seasonal demand is peaking
 
## Search Intent Classification
 
**Informational:** The reader wants to learn something. Often starts with "how", "what", "why",
"guide", "tips". Best for top-of-funnel traffic. Examples: "How to set up Google Analytics 4",
"What is ROAS?", "5 signs your email list is unhealthy".
 
**Commercial:** The reader is evaluating options before a purchase decision. Often includes
"best", "vs", "review", "comparison", "alternatives". Best for mid-funnel. Examples: "Best
project management tools for small teams", "HubSpot vs Salesforce for SMBs".
 
**Transactional:** The reader is ready to take action. Often includes "buy", "pricing", "free
trial", "hire", "agency". Best for bottom-of-funnel. Examples: "Google Ads agency pricing",
"hire a content writer".
 
**Navigational:** The reader is looking for a specific site or resource. Rarely a content
opportunity unless the brand name is being searched.
 
## Difficulty Rating Rubric
 
**Easy:**
- Topic can be covered with publicly available information
- No expert interviews or proprietary data required
- A competent writer can complete it with 1–2 hours of research
- Examples: listicles, how-to guides on well-documented topics
 
**Medium:**
- Topic requires synthesis of multiple sources or some domain expertise
- May benefit from one expert quote or a specific data source
- Examples: comparison pieces, opinion/thought leadership, trend analysis
 
**Hard:**
- Topic requires deep domain expertise, original research, or proprietary data
- Expert interviews strongly recommended
- Risk of thin or low-quality output without adequate research investment
- Examples: technical deep-dives, original survey-based reports, case studies requiring
  client permission and data access
 
## Avoiding Topic Overlap
 
When checking for overlap with recent topics:
- Same core subject = overlap (avoid)
- Same title format with different subject = acceptable
- Same angle on a different audience segment = acceptable if the difference is meaningful
- Refreshing a topic published 12+ months ago = acceptable (update post, not new post)
 
## Format × Word Count Guide
| Format | Target Word Count |
|---|---|
| How-to guide | 1,500–2,500 |
| Listicle (5–10 items) | 1,200–2,000 |
| Comparison / buyer's guide | 2,500–4,000 |
| Case study | 1,000–1,800 |
| Opinion / thought leadership | 800–1,500 |
| News analysis | 600–1,200 |
| Interview | 1,200–2,000 |