Detect and analyze trending market themes across sectors. Use when user asks about current market themes, trending sectors, sector rotation, thematic investing, what themes are hot or cold, or wants to identify bullish and bearish market narratives with lifecycle analysis.

Theme Detector Overview This skill detects and ranks trending market themes by analyzing cross sector momentum, volume, and breadth signals. It identifies both bullish (upward momentum) and bearish (downward pressure) themes, assesses lifecycle maturity (Emerging/Accelerating/Trending/Mature/Exhausting), and provides a confidence score combining quantitative data with narrative analysis. 3 Dimensional Scoring Model: 1. Theme Heat (0 100): Direction neutral strength of the theme (momentum, volume, uptrend ratio, breadth) 2. Lifecycle Maturity : Stage classification (Emerging / Accelerating / Trending / Mature / Exhausting) based on duration, extremity clustering, valuation, and ETF proliferation 3. Confidence (Low / Medium / High): Reliability of the detection, combining quantitative breadth with narrative confirmation. Script output is capped at Medium; Claude's WebSearch narrative confirmation step can elevate to High. 4. Stock Leadership : Optional daily scan hit evidence from 5D+20%, EP9M, range expansion, new highs, and high RS stocks. When supplied, this is blended into Theme Heat v2; when absent, it lowers confidence coverage but does not force leadership to zero. 5. Theme Match Quality : Specificity of the theme match from industry participation, explicit stock basket hits, proxy ETF confirmation, and optional offline narrative scores. This is evidence quality, not a trade recommendation. Key Features: Cross sector theme detection using FINVIZ industry data Direction aware scoring (bullish and bearish themes) Lifecycle maturity assessment to identify crowded vs. emerging trades ETF proliferation scoring (more ETFs = more mature/crowded theme) Integration with uptrend dashboard for 3 point evaluation Stock level leadership evidence via scan hits Theme match quality via explicit stock baskets and proxy ETF confirmation Leader candidate evidence ranked by abnormal move/volume/range/RS metrics, with market cap shown only as a risk bucket Theme history and acceleration metrics via history file Dual mode operation: FINVIZ Elite (fast) or public scraping (slower, limited) WebSearch based narrative confirmation for top themes When to Use This Skill Explicit Triggers: "What market themes are trending right now?" "Which sectors are hot/cold?" "Detect current market themes" "What are the strongest bullish/bearish narratives?" "Is AI/clean energy/defense still a strong theme?" "Where is sector rotation heading?" "Show me thematic investing opportunities" Implicit Triggers: User wants to understand broad market narrative shifts User is looking for thematic ETF or sector allocation ideas User asks about crowded trades or late cycle themes User wants to know which themes are emerging vs. exhausted When NOT to Use: Individual stock analysis (use us stock analysis instead) Specific sector deep dive with chart reading (use sector analyst instead) Portfolio rebalancing (use portfolio manager instead) Dividend/income investing (use value dividend screener instead) Prerequisites Required: Python 3.9+ with core dependencies. Cron / mixed Python fallback: If the active python3 is older than 3.10, or a newer Hermes venv lacks the data science dependencies, run the detector through uv with an explicit modern interpreter and temporary dependencies instead of editing the environment mid cron: Use this as a setup workaround, not as evidence that the detector is broken; still report FINVIZ/FMP/API data caveats separately. Optional API Keys: FINVIZ Elite (recommended for full industry coverage and speed): FMP API (optional, for P/E ratio valuation data): The requirements include finvizfinance , PyYAML, pandas/numpy, requests, and yfinance because normal public mode execution imports or uses each of them. Without FINVIZ Elite, the skill uses public FINVIZ scraping (limited to ~20 stocks per industry, slower rate limits). Workflow Step 1: Verify Environment Check that API keys are configured (see Prerequisites): Step 2: Execute Theme Detection Script Run the main detection script: Script Options: Scan hit input contract: scan hits accepts JSON, JSONL, or CSV. Rows may be pre labeled with scan type / scan types , or raw rows with fields such as symbol , return 5d , change pct , volume , avg volume 50d , relative volume , true range , atr 20 , atr expansion , close location , industry , sector , and theme guess . A raw row can expand into multiple hits when it satisfies multiple rules. Initial scan rules: five day 20pct : return 5d = 20 ep9m : volume = 9,000,000 , relative volume = 2.0 , and change pct = 4 range expansion : change pct = 4 , true range / atr 20 = 1.5 or atr expansion = 1.5 , and close location = 0.75 new high : explicit new high / is new high , or 52 week high evidence high rs : rs rating = 90 or normalized relative strength = 0.90 Narrative score input contract: narrative scores is an offline JSON input, not a live WebSearch call. It accepts either {"Theme Name": 82} or {"themes": {"Theme Name": {"narrative keyword score": 82}}} . Missing narrative input leaves narrative keyword score as null and reduces theme match coverage ; it does not fail the run. Expected Execution Time: FINVIZ Elite mode: ~2 3 minutes (14+ themes) Public FINVIZ mode: ~5 8 minutes (rate limited scraping) Step 3: Read and Parse Detection Results The script generates two output files: theme detector YYYY MM DD HHMMSS.json Structured data for programmatic use theme detector YYYY MM DD HHMMSS.md Human readable report Read the JSON output to understand quantitative results: Step 4: Perform Narrative Confirmation via WebSearch For the top 5 themes (by Theme Heat score), execute WebSearch queries to confirm narrative strength: Search Pattern: Evaluate narrative signals: Strong narrative : Multiple major outlets covering the theme, analyst upgrades, policy catalysts Moderate narrative : Some coverage, mixed sentiment, no clear catalyst Weak narrative : Little coverage, or predominantly contrarian/skeptical tone Update Confidence levels based on findings: Quantitative High + Narrative Strong = High confidence Quantitative High + Narrative Weak = Medium confidence (possible momentum divergence) Quantitative Low + Narrative Strong = Medium confidence (narrative may lead price) Quantitative Low + Narrative Weak = Low confidence Step 5: Analyze Results and Provide Recommendations Cross reference detection results with knowledge bases: Reference Documents to Consult: 1. references/cross sector themes.md Theme definitions and constituent industries 2. references/thematic etf catalog.md ETF exposure options by theme 3. references/theme detection methodology.md Scoring model details 4. references/finviz industry codes.md Industry classification reference Analysis Framework: For Hot Bullish Themes (Heat = 70, Direction = Bullish): Identify lifecycle stage (Emerging = opportunity, Mature/Exhausting = caution) List top performing industries within the theme Recommend proxy ETFs for exposure Flag if ETF proliferation is high (crowded trade warning) For Hot Bearish Themes (Heat = 70, Direction = Bearish): Identify industries under pressure Assess if bearish momentum is accelerating or decelerating Recommend hedging strategies or sectors to avoid Note potential mean reversion opportunities if lifecycle is Mature/Exhausting For Emerging Themes (Heat 40 69, Lifecycle = Emerging): These may represent early rotation signals Recommend monitoring with watchlist Identify catalyst events that could accelerate the theme For Exhausted Themes (Heat = 60, Lifecycle = Exhausting): Warn about crowded trade risk High ETF count confirms excessive retail participation Consider contrarian positioning or reducing exposure Step 6: Generate Final Report Present the final report to the user using the report template structure: Save the report to reports/ directory. Output The skill generates two output files in the reports/ directory: JSON Output ( theme detector YYYY MM DD HHMMSS.json ): Markdown Report ( theme detector YYYY MM DD HHMMSS.md ): Theme Dashboard with sortable rankings Bullish/Bearish theme detail sections Industry performance rankings Sector uptrend ratio summary Methodology notes 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 (script caps at Medium; WebSearch can elevate) representative stocks Top ticker symbols for the theme stock details Optional stock metric objects for the selected representatives proxy etfs Thematic ETF tickers (length = ETF count; higher = more crowded) theme match score 0 100 evidence quality score from industries, stock basket hits, proxy ETF confirmation, and optional narrative input theme match components Inspectable sub scores explaining the theme match leader candidates Evidence ranked symbols for the theme; not entry/stop/invalidation guidance fresh leadership symbols Current run symbols with EP9M, range expansion, or new high evidence extended symbols Current run symbols with 5D+20% evidence; used as overextension evidence only theme origin "seed" (from YAML config) or "discovered" (auto clustered) Resources Scripts Directory ( scripts/ ) Main Scripts: theme detector.py Main orchestrator script Coordinates industry data collection, theme classification, and scoring Generates JSON + Markdown output Usage: python3 theme detector.py [options] theme classifier.py Maps industries to cross sector themes Reads theme definitions from cross sector themes.md Calculates theme level aggregated scores Determines direction (bullish/bearish) from constituent industries Display mapping: "bullish" → "LEAD", "bearish" → "LAG" (see report generator.py:: direction label()) finviz industry scanner.py FINVIZ industry data collection Elite mode: CSV export with full stock data per industry Public mode: Web scraping with rate limiting Extracts: performance, volume, change%, avg volume, market cap calculators/lifecycle calculator.py Lifecycle maturity assessment Duration scoring, extremity clustering, valuation analysis ETF proliferation scoring from thematic etf catalog.md Stage classification: Emerging / Accelerating / Trending / Mature / Exhausting report generator.py Report output generation Markdown report from template JSON structured output Theme dashboard formatting References Directory ( references/ ) Knowledge Bases: cross sector themes.md Theme definitions with industries, ETFs, stocks, and matching criteria thematic etf catalog.md Comprehensive thematic ETF catalog with counts per theme finviz industry codes.md Complete FINVIZ industry to filter code mapping theme detection methodology.md Technical documentation of the 3D scoring model Assets Directory ( assets/ ) report template.md Markdown template for report generation with placeholder format Exchange Calendar and Replay Install requirements.txt before running the detector. as of date is a strict YYYY MM DD ceiling used by both uptrend freshness checks and provider history windows. Because FINVIZ, quote, profile, and uptrend inputs are live rather than PIT snapshots, a non current as of date fails closed. Freshness counts XNYS sessions and excludes future dated source rows. Important Notes FINVIZ

theme-detector