theme-detector

---
name: theme-detector
description: Use when the user asks about current market themes, trending or fading sectors, sector rotation, thematic investing, or wants ranked bullish/bearish narratives with lifecycle and confidence scoring.
category: Market & Macro
version: 1.0.0
tools: []
---

# Theme Detector

Detect and rank trending market themes by analyzing cross-sector momentum, volume, and breadth signals using FINVIZ industry data. Identify both bullish (upward momentum) and bearish (downward pressure) themes, assess lifecycle maturity, and produce a confidence score that combines quantitative data with narrative confirmation.

## When to Use
- "What market themes are trending right now?" / "Which sectors are hot or cold?"
- "What are the strongest bullish or bearish narratives?"
- "Is AI / clean energy / defense still a strong theme?" / "Where is sector rotation heading?"
- User wants thematic ETF or sector allocation ideas, or wants to know which themes are emerging vs. exhausted.

Not for single-stock analysis, one-sector chart reading, portfolio rebalancing, or dividend/income screening.

## 3-Dimensional Scoring Model
1. **Theme Heat** (0-100): direction-neutral strength of the theme, combining momentum, volume, uptrend ratio, and breadth.
2. **Lifecycle Maturity**: stage classification — Emerging / Accelerating / Trending / Mature / Exhausting — based on duration, extremity clustering, valuation, and ETF proliferation (more ETFs tracking a theme signals a more mature, crowded trade).
3. **Confidence** (Low / Medium / High): reliability of the detection, combining quantitative breadth with narrative confirmation. Quantitative evidence alone caps at Medium; a narrative-confirmation pass via web_search can elevate a theme to High.
4. **Stock Leadership**: evidence from daily scan hits — 5-day +20% movers, EP9M (9M+ volume, 2x+ relative volume, 4%+ change), range expansion, new highs, and high relative-strength (RS ≥ 90) stocks. When available this blends into Theme Heat; when absent it lowers confidence coverage rather than zeroing out leadership.
5. **Theme Match Quality**: specificity of the theme match, drawn from industry participation, explicit stock-basket hits, proxy ETF confirmation, and optional narrative keyword scores. This is evidence quality, not a trade recommendation.

## Methodology

### 1. Gather Theme Data
Use knowledge_base_search for FINVIZ industry data and any available sector momentum, volume, breadth, or scan-hit figures. Cross-sector detection compares industries against each other to find where momentum and volume are concentrating.

Scan-hit criteria (Stockbee/Pradeep-style leadership evidence):
- **5-day +20%**: 5-day return ≥ 20%
- **EP9M**: volume ≥ 9,000,000, relative volume ≥ 2.0, and change ≥ 4%
- **Range expansion**: change ≥ 4%, true range/ATR(20) ≥ 1.5 (or ATR expansion ≥ 1.5), and close location ≥ 0.75
- **New high**: explicit new-high flag or 52-week-high evidence
- **High RS**: RS rating ≥ 90 (or normalized relative strength ≥ 0.90)

### 2. Score and Rank
Compute Theme Heat, Lifecycle stage, and Theme Match Quality per theme using the model above, then rank themes by Heat within each direction (bullish/bearish).

### 3. Narrative Confirmation
For the top 5 themes by Theme Heat, use web_search to confirm narrative strength: **Strong** (multiple major outlets, analyst upgrades, clear catalysts), **Moderate** (some coverage, mixed sentiment, no clear catalyst), or **Weak** (little coverage, or predominantly skeptical tone). Combine with the quantitative signal per the Confidence rules above.

### 4. Apply the Analysis Framework
**Analysis Framework:**
- **Hot Bullish Themes** (Heat ≥ 70, bullish): identify lifecycle stage (Emerging = opportunity, Mature/Exhausting = caution), list top-performing industries, suggest proxy ETF exposure, and flag high ETF proliferation as a crowded-trade warning.
- **Hot Bearish Themes** (Heat ≥ 70, bearish): identify industries under pressure, assess whether bearish momentum is accelerating or decelerating, suggest hedging or sectors to avoid, and note mean-reversion potential if the lifecycle is Mature/Exhausting.
- **Emerging Themes** (Heat 40-69, Emerging lifecycle): treat as early rotation signals worth monitoring; identify catalysts that could accelerate the theme.
- **Exhausted Themes** (Heat ≥ 60, Exhausting lifecycle): warn about crowded-trade risk — a high ETF count confirms excessive retail participation — and consider contrarian positioning.

### 5. Report
Present a Theme Dashboard (Heat, Direction, Lifecycle, Confidence per theme), a "What Changed" summary (newly emerging themes, largest heat acceleration, fading themes), leadership evidence (5-day +20%, EP9M, range expansion, new highs, high-RS counts and leader symbols), bullish and bearish detail sections sorted by Heat, industry rankings, and a brief methodology note — returned directly in the chat.

## Data Modes and Quality
Two data modes are possible: a fast, full-coverage mode against a premium industry-data feed (covers 150+ industries with deeper per-stock detail), or a slower public-scraping mode limited to roughly 20 stocks per industry and stricter rate limits. Either mode works for detection; note which mode was used and any resulting coverage limitations in the Data Quality section of the report, since it affects how much weight to put on thin-coverage themes.

Theme history and acceleration should be tracked over time where prior runs are available — compare today's Heat and Stage against the prior reading per theme to compute acceleration and flag newly Emerging or newly Exhausting themes. Where explicit stock baskets or proxy-ETF momentum are supplied for a theme, prefer them over generic industry matching for Theme Match Quality, since a named basket is stronger evidence than an industry-code heuristic alone.

## Key Output Fields (per theme)
| Field | Description |
|-------|-------------|
| Heat | 0-100 direction-neutral theme strength |
| Direction | Bullish (LEAD) or Bearish (LAG) |
| Stage | Emerging / Accelerating / Trending / Mature / Exhausting |
| Confidence | Low / Medium / High |
| Representative stocks | Top ticker symbols for the theme |
| Proxy ETFs | Thematic ETF tickers — count reflects crowding |
| Theme match score | 0-100 evidence-quality score for the theme match |
| Leader candidates | Stocks ranked by abnormal move/volume/range/RS, with market cap shown only as a risk bucket |