Skill: Stock Analysis

Owner: udiedrichsen

Summary: Analyze stocks and cryptocurrencies using Yahoo Finance data. Supports portfolio management, watchlists with alerts, dividend analysis, 8-dimension stock scoring, viral trend detection (Hot Scanner), and rumor/early signal detection. Use for stock analysis, portfolio tracking, earnings reactions, crypto monitoring, trending stocks, or finding rumors before they hit mainstream.

Tags: latest:6.2.0

Version history:

v6.2.0 | 2026-02-02T14:09:13.575Z | user

🔮 Rumor Scanner: M&A rumors, insider activity, Twitter whispers, impact scoring

v6.1.0 | 2026-02-02T11:07:39.843Z | auto

Major update: Viral trend detection ("Hot Scanner") and social media integration.

• Added Hot Scanner to detect trending stocks and crypto from CoinGecko, Yahoo Finance, Google News, and Twitter/X.
• Introduced new /stock_hot command for finding viral assets.
• Added Twitter/X integration for social sentiment in Hot Scanner (optional setup).
• Expanded documentation: new concept, architecture, usage, and hot scanner docs.
• Enhanced cron support for daily trend reports.
• Existing features (analysis, alerts, dividend, portfolio) unchanged.

v6.0.0 | 2026-02-02T09:07:24.446Z | user

Watchlist + Alerts, Dividend Analysis, Fast Mode, Tests

v5.0.0 | 2026-01-16T09:33:36.509Z | user

Portfolio management, crypto analysis (Top 20), periodic reports (daily/weekly/monthly/quarterly/yearly)

v4.0.0 | 2026-01-15T07:11:12.536Z | user

v4.0.0: Geopolitical Risk & News Sentiment

Major new features: • Safe-haven indicators (GLD, TLT, UUP) with risk-off detection • Breaking news check (Google News RSS) for crisis keywords • Geopolitical sector risk mapping (Taiwan, China, Russia, Middle East, banking) • Automatic confidence penalties for affected tickers/sectors (15-30%) • Up to 5 caveats in output (was 3)

Risk detection: • Flight to safety detection across gold, treasuries, USD • Crisis keyword scanning (war, recession, sanctions, disasters) • Sector-specific exposure warnings • 1-hour cache for breaking news and shared indicators

v3.5.0 | 2026-01-15T06:39:48.890Z | user

Major performance upgrade: Async parallel fetching (6-10s → 3-5s per stock) + caching for shared indicators (Fear/Greed, VIX). Multi-stock analysis now ~3x faster. All 5 sentiment indicators fetch in parallel with 10s timeouts. Fear & Greed Index and VIX term structure cached for 1h.

v3.0.0 | 2026-01-15T06:10:37.779Z | user

Add comprehensive sentiment analysis with 5 indicators: Fear & Greed Index, short interest, VIX term structure, insider trading, and put/call ratio. Sentiment adds 10% weight to overall recommendation. Runtime increased to 6-10s per stock.

v2.0.0 | 2026-01-14T16:31:21.094Z | user

Major enhancement: Added market context (VIX, SPY/QQQ), sector performance comparison, earnings timing warnings (pre/post-earnings), and momentum analysis (RSI, 52w range). Now detects 'sell the news' scenarios, overbought conditions, and sector rotation. Helps avoid losses like the BAC scenario by warning about high-risk entry points. All 7 dimensions now analyzed with smart recommendation overrides.

v1.0.1 | 2026-01-14T15:21:58.281Z | user

Fix: Add explicit instructions to prevent agent from adding extra text in command invocation

v1.0.0 | 2026-01-14T09:46:15.214Z | user

Initial release: Analyze US stocks during earnings season with buy/hold/sell signals based on earnings surprises, fundamentals (P/E, margins, growth, debt), analyst sentiment, and historical patterns. Uses Yahoo Finance data via yfinance library.

Archive index:

Archive v6.2.0: 18 files, 80513 bytes

Files: App-Plan.md (14708b), docs/ARCHITECTURE.md (16594b), docs/CONCEPT.md (9101b), docs/HOT_SCANNER.md (5865b), docs/README.md (2405b), docs/USAGE.md (8898b), README.md (6390b), scripts/analyze_stock.py (89930b), scripts/dividends.py (13130b), scripts/hot_scanner.py (24620b), scripts/portfolio.py (18897b), scripts/rumor_scanner.py (11578b), scripts/test_stock_analysis.py (11958b), scripts/watchlist.py (11542b), skill-card.md (2643b), SKILL.md (8230b), TODO.md (12848b), _meta.json (133b)

File v6.2.0:SKILL.md

---

name: stock-analysis description: Analyze stocks and cryptocurrencies using Yahoo Finance data. Supports portfolio management, watchlists with alerts, dividend analysis, 8-dimension stock scoring, viral trend detection (Hot Scanner), and rumor/early signal detection. Use for stock analysis, portfolio tracking, earnings reactions, crypto monitoring, trending stocks, or finding rumors before they hit mainstream. version: 6.2.0 homepage: https://finance.yahoo.com commands:

• /stock - Analyze a stock or crypto (e.g., /stock AAPL)
• /stock_compare - Compare multiple tickers
• /stock_dividend - Analyze dividend metrics
• /stock_watch - Add/remove from watchlist
• /stock_alerts - Check triggered alerts
• /stock_hot - Find trending stocks & crypto (Hot Scanner)
• /stock_rumors - Find early signals, M&A rumors, insider activity (Rumor Scanner)
• /portfolio - Show portfolio summary
• /portfolio_add - Add asset to portfolio metadata: {"clawdbot":{"emoji":"📈","requires":{"bins":["uv"],"env":[]},"install":[{"id":"uv-brew","kind":"brew","formula":"uv","bins":["uv"],"label":"Install uv (brew)"}]}}

---

Stock Analysis v6.1

Analyze US stocks and cryptocurrencies with 8-dimension analysis, portfolio management, watchlists, alerts, dividend analysis, and viral trend detection.

What's New in v6.2

• 🔮 Rumor Scanner — Early signals before mainstream news
  • M&A rumors and takeover bids
  • Insider buying/selling activity
  • Analyst upgrades/downgrades
  • Twitter/X "hearing that...", "sources say..." detection
• 🎯 Impact Scoring — Rumors ranked by potential market impact

What's in v6.1

• 🔥 Hot Scanner — Find viral stocks & crypto across multiple sources
• 🐦 Twitter/X Integration — Social sentiment via bird CLI
• 📰 Multi-Source Aggregation — CoinGecko, Google News, Yahoo Finance
• ⏰ Cron Support — Daily trend reports

What's in v6.0

• 🆕 Watchlist + Alerts — Price targets, stop losses, signal changes
• 🆕 Dividend Analysis — Yield, payout ratio, growth, safety score
• 🆕 Fast Mode — --fast skips slow analyses (insider, news)
• 🆕 Improved Performance — --no-insider for faster runs

Quick Commands

Stock Analysis

# Basic analysis
uv run {baseDir}/scripts/analyze_stock.py AAPL

# Fast mode (skips insider trading & breaking news)
uv run {baseDir}/scripts/analyze_stock.py AAPL --fast

# Compare multiple
uv run {baseDir}/scripts/analyze_stock.py AAPL MSFT GOOGL

# Crypto
uv run {baseDir}/scripts/analyze_stock.py BTC-USD ETH-USD

Dividend Analysis (NEW v6.0)

# Analyze dividends
uv run {baseDir}/scripts/dividends.py JNJ

# Compare dividend stocks
uv run {baseDir}/scripts/dividends.py JNJ PG KO MCD --output json

Dividend Metrics:

• Dividend Yield & Annual Payout
• Payout Ratio (safe/moderate/high/unsustainable)
• 5-Year Dividend Growth (CAGR)
• Consecutive Years of Increases
• Safety Score (0-100)
• Income Rating (excellent/good/moderate/poor)

Watchlist + Alerts (NEW v6.0)

# Add to watchlist
uv run {baseDir}/scripts/watchlist.py add AAPL

# With price target alert
uv run {baseDir}/scripts/watchlist.py add AAPL --target 200

# With stop loss alert
uv run {baseDir}/scripts/watchlist.py add AAPL --stop 150

# Alert on signal change (BUY→SELL)
uv run {baseDir}/scripts/watchlist.py add AAPL --alert-on signal

# View watchlist
uv run {baseDir}/scripts/watchlist.py list

# Check for triggered alerts
uv run {baseDir}/scripts/watchlist.py check
uv run {baseDir}/scripts/watchlist.py check --notify  # Telegram format

# Remove from watchlist
uv run {baseDir}/scripts/watchlist.py remove AAPL

Alert Types:

• 🎯 Target Hit — Price >= target
• 🛑 Stop Hit — Price <= stop
• 📊 Signal Change — BUY/HOLD/SELL changed

Portfolio Management

# Create portfolio
uv run {baseDir}/scripts/portfolio.py create "Tech Portfolio"

# Add assets
uv run {baseDir}/scripts/portfolio.py add AAPL --quantity 100 --cost 150
uv run {baseDir}/scripts/portfolio.py add BTC-USD --quantity 0.5 --cost 40000

# View portfolio
uv run {baseDir}/scripts/portfolio.py show

# Analyze with period returns
uv run {baseDir}/scripts/analyze_stock.py --portfolio "Tech Portfolio" --period weekly

🔥 Hot Scanner (NEW v6.1)

# Full scan - find what's trending NOW
python3 {baseDir}/scripts/hot_scanner.py

# Fast scan (skip social media)
python3 {baseDir}/scripts/hot_scanner.py --no-social

# JSON output for automation
python3 {baseDir}/scripts/hot_scanner.py --json

Data Sources:

• 📊 CoinGecko Trending — Top 15 trending coins
• 📈 CoinGecko Movers — Biggest gainers/losers
• 📰 Google News — Finance & crypto headlines
• 📉 Yahoo Finance — Gainers, losers, most active
• 🐦 Twitter/X — Social sentiment (requires auth)

Output:

• Top trending by mention count
• Crypto highlights with 24h changes
• Stock movers by category
• Breaking news with tickers

Twitter Setup (Optional):

1. Install bird: npm install -g @steipete/bird
2. Login to x.com in Safari/Chrome
3. Create .env with AUTH_TOKEN and CT0

🔮 Rumor Scanner (NEW v6.2)

# Find early signals, M&A rumors, insider activity
python3 {baseDir}/scripts/rumor_scanner.py

What it finds:

• 🏢 M&A Rumors — Merger, acquisition, takeover bids
• 👔 Insider Activity — CEO/Director buying/selling
• 📊 Analyst Actions — Upgrades, downgrades, price target changes
• 🐦 Twitter Whispers — "hearing that...", "sources say...", "rumor"
• ⚖️ SEC Activity — Investigations, filings

Impact Scoring:

• Each rumor is scored by potential market impact (1-10)
• M&A/Takeover: +5 points
• Insider buying: +4 points
• Upgrade/Downgrade: +3 points
• "Hearing"/"Sources say": +2 points
• High engagement: +2 bonus

Best Practice: Run at 07:00 before US market open to catch pre-market signals.

Analysis Dimensions (8 for stocks, 3 for crypto)

Stocks

| Dimension | Weight | Description | |-----------|--------|-------------| | Earnings Surprise | 30% | EPS beat/miss | | Fundamentals | 20% | P/E, margins, growth | | Analyst Sentiment | 20% | Ratings, price targets | | Historical | 10% | Past earnings reactions | | Market Context | 10% | VIX, SPY/QQQ trends | | Sector | 15% | Relative strength | | Momentum | 15% | RSI, 52-week range | | Sentiment | 10% | Fear/Greed, shorts, insiders |

Crypto

• Market Cap & Category
• BTC Correlation (30-day)
• Momentum (RSI, range)

Sentiment Sub-Indicators

| Indicator | Source | Signal | |-----------|--------|--------| | Fear & Greed | CNN | Contrarian (fear=buy) | | Short Interest | Yahoo | Squeeze potential | | VIX Structure | Futures | Stress detection | | Insider Trades | SEC EDGAR | Smart money | | Put/Call Ratio | Options | Sentiment extreme |

Risk Detection

• ⚠️ Pre-Earnings — Warns if < 14 days to earnings
• ⚠️ Post-Spike — Flags if up >15% in 5 days
• ⚠️ Overbought — RSI >70 + near 52w high
• ⚠️ Risk-Off — GLD/TLT/UUP rising together
• ⚠️ Geopolitical — Taiwan, China, Russia, Middle East keywords
• ⚠️ Breaking News — Crisis keywords in last 24h

Performance Options

| Flag | Effect | Speed | |------|--------|-------| | (default) | Full analysis | 5-10s | | --no-insider | Skip SEC EDGAR | 3-5s | | --fast | Skip insider + news | 2-3s |

Supported Cryptos (Top 20)

BTC, ETH, BNB, SOL, XRP, ADA, DOGE, AVAX, DOT, MATIC, LINK, ATOM, UNI, LTC, BCH, XLM, ALGO, VET, FIL, NEAR

(Use -USD suffix: BTC-USD, ETH-USD)

Data Storage

| File | Location | |------|----------| | Portfolios | ~/.clawdbot/skills/stock-analysis/portfolios.json | | Watchlist | ~/.clawdbot/skills/stock-analysis/watchlist.json |

Limitations

• Yahoo Finance may lag 15-20 minutes
• Short interest lags ~2 weeks (FINRA)
• Insider trades lag 2-3 days (SEC filing)
• US markets only (non-US incomplete)
• Breaking news: 1h cache, keyword-based

Disclaimer

⚠️ NOT FINANCIAL ADVICE. For informational purposes only. Consult a licensed financial advisor before making investment decisions.

File v6.2.0:docs/README.md

Documentation

Stock Analysis v6.1

This folder contains detailed documentation for the Stock Analysis skill.

Contents

| Document | Description | |----------|-------------| | CONCEPT.md | Philosophy, ideas, and design rationale | | USAGE.md | Practical usage guide with examples | | ARCHITECTURE.md | Technical implementation details | | HOT_SCANNER.md | 🔥 Viral trend detection (NEW) |

Quick Links

For Users

Start with USAGE.md — it has practical examples for:

• Basic stock analysis
• Comparing stocks
• Crypto analysis
• Dividend investing
• Portfolio management
• Watchlist & alerts

For Understanding

Read CONCEPT.md to understand:

• Why 8 dimensions?
• How scoring works
• Contrarian signals
• Risk detection philosophy
• Limitations we acknowledge

For Developers

Check ARCHITECTURE.md for:

• System overview diagram
• Data flow
• Caching strategy
• File structure
• Performance optimization

Quick Start

# Analyze a stock
uv run scripts/analyze_stock.py AAPL

# Fast mode (2-3 seconds)
uv run scripts/analyze_stock.py AAPL --fast

# Dividend analysis
uv run scripts/dividends.py JNJ

# Watchlist
uv run scripts/watchlist.py add AAPL --target 200
uv run scripts/watchlist.py check

Key Concepts

The 8 Dimensions

1. Earnings Surprise (30%) — Did they beat expectations?
2. Fundamentals (20%) — P/E, margins, growth, debt
3. Analyst Sentiment (20%) — Professional consensus
4. Historical Patterns (10%) — Past earnings reactions
5. Market Context (10%) — VIX, SPY/QQQ trends
6. Sector Performance (15%) — Relative strength
7. Momentum (15%) — RSI, 52-week range
8. Sentiment (10%) — Fear/Greed, shorts, insiders

Signal Thresholds

| Score | Recommendation | |-------|----------------| | > +0.33 | BUY | | -0.33 to +0.33 | HOLD | | < -0.33 | SELL |

Risk Flags

• ⚠️ Pre-earnings (< 14 days)
• ⚠️ Post-spike (> 15% in 5 days)
• ⚠️ Overbought (RSI > 70 + near 52w high)
• ⚠️ Risk-off mode (GLD/TLT/UUP rising)
• ⚠️ Geopolitical keywords
• ⚠️ Breaking news alerts

Disclaimer

⚠️ NOT FINANCIAL ADVICE. For informational purposes only. Always do your own research and consult a licensed financial advisor.

File v6.2.0:README.md

📈 Stock Analysis v6.1

AI-powered stock & crypto analysis with portfolio management, watchlists, dividend analysis, and viral trend detection.

What's New in v6.1

• 🔥 Hot Scanner — Find viral stocks & crypto across multiple sources
• 🐦 Twitter/X Integration — Social sentiment via bird CLI
• 📰 Multi-Source Aggregation — CoinGecko, Google News, Yahoo Finance
• ⏰ Cron Support — Daily trend reports

What's New in v6.0

• 🆕 Watchlist + Alerts — Price targets, stop losses, signal change notifications
• 🆕 Dividend Analysis — Yield, payout ratio, growth rate, safety score
• 🆕 Fast Mode — Skip slow analyses for quick checks
• 🆕 Improved Commands — Better OpenClaw/Telegram integration
• 🆕 Test Suite — Unit tests for core functionality

Features

| Feature | Description | |---------|-------------| | 8-Dimension Analysis | Earnings, fundamentals, analysts, momentum, sentiment, sector, market, history | | Crypto Support | Top 20 cryptos with market cap, BTC correlation, momentum | | Portfolio Management | Track holdings, P&L, concentration warnings | | Watchlist + Alerts | Price targets, stop losses, signal changes | | Dividend Analysis | Yield, payout, growth, safety score | | Risk Detection | Geopolitical, earnings timing, overbought, risk-off | | Breaking News | Crisis keyword scanning (last 24h) |

Quick Start

Analyze Stocks

uv run scripts/analyze_stock.py AAPL
uv run scripts/analyze_stock.py AAPL MSFT GOOGL
uv run scripts/analyze_stock.py AAPL --fast  # Skip slow analyses

Analyze Crypto

uv run scripts/analyze_stock.py BTC-USD
uv run scripts/analyze_stock.py ETH-USD SOL-USD

Dividend Analysis

uv run scripts/dividends.py JNJ PG KO

Watchlist

uv run scripts/watchlist.py add AAPL --target 200 --stop 150
uv run scripts/watchlist.py list
uv run scripts/watchlist.py check --notify

Portfolio

uv run scripts/portfolio.py create "My Portfolio"
uv run scripts/portfolio.py add AAPL --quantity 100 --cost 150
uv run scripts/portfolio.py show

🔥 Hot Scanner (NEW)

# Full scan with all sources
python3 scripts/hot_scanner.py

# Fast scan (skip social media)
python3 scripts/hot_scanner.py --no-social

# JSON output for automation
python3 scripts/hot_scanner.py --json

Analysis Dimensions

Stocks (8 dimensions)

1. Earnings Surprise (30%) — EPS beat/miss
2. Fundamentals (20%) — P/E, margins, growth, debt
3. Analyst Sentiment (20%) — Ratings, price targets
4. Historical Patterns (10%) — Past earnings reactions
5. Market Context (10%) — VIX, SPY/QQQ trends
6. Sector Performance (15%) — Relative strength
7. Momentum (15%) — RSI, 52-week range
8. Sentiment (10%) — Fear/Greed, shorts, insiders

Crypto (3 dimensions)

• Market Cap & Category
• BTC Correlation (30-day)
• Momentum (RSI, range)

Dividend Metrics

| Metric | Description | |--------|-------------| | Yield | Annual dividend / price | | Payout Ratio | Dividend / EPS | | 5Y Growth | CAGR of dividend | | Consecutive Years | Years of increases | | Safety Score | 0-100 composite | | Income Rating | Excellent → Poor |

🔥 Hot Scanner

Find what's trending RIGHT NOW across stocks & crypto.

Data Sources

| Source | What it finds | |--------|---------------| | CoinGecko Trending | Top 15 trending coins | | CoinGecko Movers | Biggest gainers/losers (>3%) | | Google News | Breaking finance & crypto news | | Yahoo Finance | Top gainers, losers, most active | | Twitter/X | Social sentiment (requires auth) |

Output

📊 TOP TRENDING (by buzz):
   1. BTC      (6 pts) [CoinGecko, Google News] 📉 bearish (-2.5%)
   2. ETH      (5 pts) [CoinGecko, Twitter] 📉 bearish (-7.2%)
   3. NVDA     (3 pts) [Google News, Yahoo] 📰 Earnings beat...

🪙 CRYPTO HIGHLIGHTS:
   🚀 RIVER    River              +14.0%
   📉 BTC      Bitcoin             -2.5%

📈 STOCK MOVERS:
   🟢 NVDA (gainers)
   🔴 TSLA (losers)

📰 BREAKING NEWS:
   [BTC, ETH] Crypto crash: $2.5B liquidated...

Twitter/X Setup (Optional)

1. Install bird CLI: npm install -g @steipete/bird
2. Login to x.com in Safari/Chrome
3. Create .env file:

AUTH_TOKEN=your_auth_token
CT0=your_ct0_token

Get tokens from browser DevTools → Application → Cookies → x.com

Automation

Set up a daily cron job for morning reports:

# Run at 8 AM daily
0 8 * * * python3 /path/to/hot_scanner.py --no-social >> /var/log/hot_scanner.log

Risk Detection

• ⚠️ Pre-earnings warning (< 14 days)
• ⚠️ Post-earnings spike (> 15% in 5 days)
• ⚠️ Overbought (RSI > 70 + near 52w high)
• ⚠️ Risk-off mode (GLD/TLT/UUP rising)
• ⚠️ Geopolitical keywords (Taiwan, China, etc.)
• ⚠️ Breaking news alerts

Performance Options

| Flag | Speed | Description | |------|-------|-------------| | (default) | 5-10s | Full analysis | | --no-insider | 3-5s | Skip SEC EDGAR | | --fast | 2-3s | Skip insider + news |

Data Sources

• Yahoo Finance — Prices, fundamentals, movers
• CoinGecko — Crypto trending, market data
• CNN Fear & Greed — Sentiment
• SEC EDGAR — Insider trading
• Google News RSS — Breaking news
• Twitter/X — Social sentiment (via bird CLI)

Storage

| Data | Location | |------|----------| | Portfolios | ~/.clawdbot/skills/stock-analysis/portfolios.json | | Watchlist | ~/.clawdbot/skills/stock-analysis/watchlist.json |

Testing

uv run pytest scripts/test_stock_analysis.py -v

Limitations

• Yahoo Finance may lag 15-20 minutes
• Short interest lags ~2 weeks (FINRA)
• US markets only

Disclaimer

⚠️ NOT FINANCIAL ADVICE. For informational purposes only. Consult a licensed financial advisor before making investment decisions.

---

Built for OpenClaw 🦞 | ClawHub

File v6.2.0:_meta.json

{ "ownerId": "kn77fv9851hjcqe52zqx0bhhbx7z680h", "slug": "stock-analysis", "version": "6.2.0", "publishedAt": 1770041353575 }

File v6.2.0:App-Plan.md

StockPulse - Commercial Product Roadmap

Vision

Transform the stock-analysis skill into StockPulse, a commercial mobile app for retail investors with AI-powered stock and crypto analysis, portfolio tracking, and personalized alerts.

Technical Decisions

• Mobile: Flutter (iOS + Android cross-platform)
• Backend: Python FastAPI on AWS (ECS/Lambda)
• Database: PostgreSQL (RDS) + Redis (ElastiCache)
• Auth: AWS Cognito or Firebase Auth
• Monetization: Freemium + Subscription ($9.99/mo or $79.99/yr)

---

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                      MOBILE APP (Flutter)                        │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐           │
│  │Dashboard │ │Portfolio │ │ Analysis │ │ Alerts   │           │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘           │
└─────────────────────────────────────────────────────────────────┘
                              │ HTTPS/REST
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      API GATEWAY (AWS)                           │
│                   Rate Limiting, Auth, Caching                   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   BACKEND (FastAPI on ECS)                       │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │
│  │ Auth Service │ │ Analysis API │ │ Portfolio API│            │
│  └──────────────┘ └──────────────┘ └──────────────┘            │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │
│  │ Alerts Svc   │ │ Subscription │ │ User Service │            │
│  └──────────────┘ └──────────────┘ └──────────────┘            │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  PostgreSQL  │     │    Redis     │     │     S3       │
│   (RDS)      │     │ (ElastiCache)│     │  (Reports)   │
└──────────────┘     └──────────────┘     └──────────────┘

                    BACKGROUND WORKERS (Lambda/ECS)
┌─────────────────────────────────────────────────────────────────┐
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │
│  │Price Updater │ │Alert Checker │ │Daily Reports │            │
│  │  (5 min)     │ │  (1 min)     │ │  (Daily)     │            │
│  └──────────────┘ └──────────────┘ └──────────────┘            │
└─────────────────────────────────────────────────────────────────┘

---

Feature Tiers

Free Tier

• 1 portfolio (max 10 assets)
• Basic stock/crypto analysis
• Daily market summary
• Limited to 5 analyses/day
• Ads displayed

Premium ($9.99/mo)

• Unlimited portfolios & assets
• Full 8-dimension analysis
• Real-time price alerts
• Push notifications
• Period reports (daily/weekly/monthly)
• No ads
• Priority support

Pro ($19.99/mo) - Future

• API access
• Custom watchlists
• Advanced screeners
• Export to CSV/PDF
• Portfolio optimization suggestions

---

Development Phases

Phase 1: Backend API

Goal: Convert Python scripts to production REST API

Tasks:

1. Project Setup

   • FastAPI project structure
   • Docker containerization
   • CI/CD pipeline (GitHub Actions)
   • AWS infrastructure (Terraform)

2. Core API Endpoints

   POST /auth/register
   POST /auth/login
   POST /auth/refresh
   
   GET  /analysis/{ticker}
   POST /analysis/batch
   
   GET  /portfolios
   POST /portfolios
   PUT  /portfolios/{id}
   DELETE /portfolios/{id}
   
   GET  /portfolios/{id}/assets
   POST /portfolios/{id}/assets
   PUT  /portfolios/{id}/assets/{ticker}
   DELETE /portfolios/{id}/assets/{ticker}
   
   GET  /portfolios/{id}/performance?period=weekly
   GET  /portfolios/{id}/summary
   
   GET  /alerts
   POST /alerts
   DELETE /alerts/{id}
   
   GET  /user/subscription
   POST /user/subscription/upgrade
   

3. Database Schema

   users (id, email, password_hash, created_at, subscription_tier)
   portfolios (id, user_id, name, created_at, updated_at)
   assets (id, portfolio_id, ticker, asset_type, quantity, cost_basis)
   alerts (id, user_id, ticker, condition, threshold, enabled)
   analysis_cache (ticker, data, expires_at)
   subscriptions (id, user_id, stripe_id, status, expires_at)
   

4. Refactor Existing Code

   • Extract analyze_stock.py into modules:
     • analysis/earnings.py
     • analysis/fundamentals.py
     • analysis/sentiment.py
     • analysis/crypto.py
     • analysis/market_context.py
   • Add async support throughout
   • Implement proper caching (Redis)
   • Rate limiting per user tier

Files to Create:

backend/
├── app/
│   ├── main.py              # FastAPI app
│   ├── config.py            # Settings
│   ├── models/              # SQLAlchemy models
│   ├── schemas/             # Pydantic schemas
│   ├── routers/             # API routes
│   │   ├── auth.py
│   │   ├── analysis.py
│   │   ├── portfolios.py
│   │   └── alerts.py
│   ├── services/            # Business logic
│   │   ├── analysis/        # Refactored from analyze_stock.py
│   │   ├── portfolio.py
│   │   └── alerts.py
│   └── workers/             # Background tasks
├── tests/
├── Dockerfile
├── docker-compose.yml
└── requirements.txt

---

Phase 2: Flutter Mobile App

Goal: Build polished cross-platform mobile app

Screens:

1. Onboarding - Welcome, feature highlights, sign up/login
2. Dashboard - Market overview, portfolio summary, alerts
3. Analysis - Search ticker, view full analysis, save to portfolio
4. Portfolio - List portfolios, asset breakdown, P&L chart
5. Alerts - Manage price alerts, notification settings
6. Settings - Account, subscription, preferences

Key Flutter Packages:

dependencies:
  flutter_bloc: ^8.0.0      # State management
  dio: ^5.0.0               # HTTP client
  go_router: ^12.0.0        # Navigation
  fl_chart: ^0.65.0         # Charts
  firebase_messaging: ^14.0.0  # Push notifications
  in_app_purchase: ^3.0.0   # Subscriptions
  shared_preferences: ^2.0.0
  flutter_secure_storage: ^9.0.0

App Structure:

lib/
├── main.dart
├── app/
│   ├── routes.dart
│   └── theme.dart
├── features/
│   ├── auth/
│   │   ├── bloc/
│   │   ├── screens/
│   │   └── widgets/
│   ├── dashboard/
│   ├── analysis/
│   ├── portfolio/
│   ├── alerts/
│   └── settings/
├── core/
│   ├── api/
│   ├── models/
│   └── utils/
└── shared/
    └── widgets/

---

Phase 3: Infrastructure & DevOps

Goal: Production-ready cloud infrastructure

AWS Services:

• ECS Fargate - Backend containers
• RDS PostgreSQL - Database
• ElastiCache Redis - Caching
• S3 - Static assets, reports
• CloudFront - CDN
• Cognito - Authentication
• SES - Email notifications
• SNS - Push notifications
• CloudWatch - Monitoring
• WAF - Security

Terraform Modules:

infrastructure/
├── main.tf
├── variables.tf
├── modules/
│   ├── vpc/
│   ├── ecs/
│   ├── rds/
│   ├── elasticache/
│   └── cognito/
└── environments/
    ├── dev/
    ├── staging/
    └── prod/

Estimated Monthly Costs (Production):

| Service | Est. Cost | |---------|-----------| | ECS Fargate (2 tasks) | $50-100 | | RDS (db.t3.small) | $30-50 | | ElastiCache (cache.t3.micro) | $15-25 | | S3 + CloudFront | $10-20 | | Other (Cognito, SES, etc.) | $20-30 | | Total | $125-225/mo |

---

Phase 4: Payments & Subscriptions

Goal: Integrate Stripe for subscriptions

Implementation:

1. Stripe subscription products (Free, Premium, Pro)
2. In-app purchase for iOS/Android
3. Webhook handlers for subscription events
4. Grace period handling
5. Receipt validation

Stripe Integration:

# Backend webhook handler
@router.post("/webhooks/stripe")
async def stripe_webhook(request: Request):
    event = stripe.Webhook.construct_event(...)

    if event.type == "customer.subscription.updated":
        update_user_tier(event.data.object)
    elif event.type == "customer.subscription.deleted":
        downgrade_to_free(event.data.object)

---

Phase 5: Push Notifications & Alerts

Goal: Real-time price alerts and notifications

Alert Types:

• Price above/below threshold
• Percentage change (daily)
• Earnings announcement
• Breaking news (geopolitical)
• Portfolio performance

Implementation:

• Firebase Cloud Messaging (FCM)
• Background worker checks alerts every minute
• Rate limit: max 10 alerts/day per free user

---

Phase 6: Analytics & Monitoring

Goal: Track usage, errors, business metrics

Tools:

• Mixpanel/Amplitude - Product analytics
• Sentry - Error tracking
• CloudWatch - Infrastructure metrics
• Custom dashboard - Business KPIs

Key Metrics:

• DAU/MAU
• Conversion rate (free → premium)
• Churn rate
• API response times
• Analysis accuracy feedback

---

Security Considerations

1. Authentication

   • JWT tokens with refresh rotation
   • OAuth2 (Google, Apple Sign-In)
   • 2FA optional for premium users

2. Data Protection

   • Encrypt PII at rest (RDS encryption)
   • TLS 1.3 for all API traffic
   • No plaintext passwords

3. API Security

   • Rate limiting per tier
   • Input validation (Pydantic)
   • SQL injection prevention (SQLAlchemy ORM)
   • CORS configuration

4. Compliance

   • Privacy policy
   • Terms of service
   • GDPR data export/deletion
   • Financial disclaimer (not investment advice)

---

Risks & Mitigations

| Risk | Impact | Mitigation | |------|--------|------------| | Yahoo Finance rate limits | High | Implement caching, use paid API fallback | | App store rejection | Medium | Follow guidelines, proper disclaimers | | Data accuracy issues | High | Clear disclaimers, data validation | | Security breach | Critical | Security audit, penetration testing | | Low conversion rate | Medium | A/B testing, feature gating |

---

Success Metrics (Year 1)

| Metric | Target | |--------|--------| | App downloads | 10,000+ | | DAU | 1,000+ | | Premium subscribers | 500+ | | Monthly revenue | $5,000+ | | App store rating | 4.5+ stars | | Churn rate | <5%/month |

---

Next Steps (Immediate)

1. Validate idea - User interviews, landing page
2. Design - Figma mockups for key screens
3. Backend MVP - Core API endpoints
4. Flutter prototype - Basic app with analysis feature
5. Beta testing - TestFlight/Google Play beta

---

Repository Structure (Final)

stockpulse/
├── backend/                 # FastAPI backend
│   ├── app/
│   ├── tests/
│   ├── Dockerfile
│   └── requirements.txt
├── mobile/                  # Flutter app
│   ├── lib/
│   ├── test/
│   ├── ios/
│   ├── android/
│   └── pubspec.yaml
├── infrastructure/          # Terraform
│   ├── modules/
│   └── environments/
├── docs/                    # Documentation
│   ├── api/
│   └── architecture/
└── scripts/                 # Utility scripts

---

Timeline Summary (Planning Only)

| Phase | Duration | Dependencies | |-------|----------|--------------| | 1. Backend API | 4-6 weeks | - | | 2. Flutter App | 6-8 weeks | Phase 1 | | 3. Infrastructure | 2-3 weeks | Phase 1 | | 4. Payments | 2 weeks | Phase 2, 3 | | 5. Notifications | 2 weeks | Phase 2, 3 | | 6. Analytics | 1 week | Phase 2 | | Total | 17-22 weeks | |

This is a planning document. No fixed timeline - execute phases as resources allow.

---

Disclaimer: This tool is for informational purposes only and does NOT constitute financial advice.

File v6.2.0:docs/ARCHITECTURE.md

Technical Architecture

How Stock Analysis v6.0 works under the hood.

System Overview

┌─────────────────────────────────────────────────────────────────────┐
│                        Stock Analysis v6.0                           │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │                    CLI Interface                              │   │
│  │  analyze_stock.py | dividends.py | watchlist.py | portfolio.py│   │
│  └────────────────────────────┬─────────────────────────────────┘   │
│                               │                                      │
│  ┌────────────────────────────▼─────────────────────────────────┐   │
│  │                   Analysis Engine                             │   │
│  │                                                               │   │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐            │   │
│  │  │Earnings │ │Fundmtls │ │Analysts │ │Historical│            │   │
│  │  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘            │   │
│  │       │           │           │           │                   │   │
│  │  ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐            │   │
│  │  │ Market  │ │ Sector  │ │Momentum │ │Sentiment│            │   │
│  │  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘            │   │
│  │       │           │           │           │                   │   │
│  │       └───────────┴───────────┴───────────┘                   │   │
│  │                          │                                    │   │
│  │                    [Synthesizer]                              │   │
│  │                          │                                    │   │
│  │                    [Signal Output]                            │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                               │                                      │
│  ┌────────────────────────────▼─────────────────────────────────┐   │
│  │                    Data Sources                               │   │
│  │                                                               │   │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐            │   │
│  │  │ Yahoo   │ │  CNN    │ │   SEC   │ │ Google  │            │   │
│  │  │ Finance │ │Fear/Grd │ │ EDGAR   │ │  News   │            │   │
│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘            │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

---

Core Components

1. Data Fetching (fetch_stock_data)

def fetch_stock_data(ticker: str, verbose: bool = False) -> StockData | None:
    """Fetch stock data from Yahoo Finance with retry logic."""

Features:

• 3 retries with exponential backoff
• Graceful handling of missing data
• Asset type detection (stock vs crypto)

Returns: StockData dataclass with:

• info: Company fundamentals
• earnings_history: Past earnings
• analyst_info: Ratings and targets
• price_history: 1-year OHLCV

2. Analysis Modules

Each dimension has its own analyzer:

| Module | Function | Returns | |--------|----------|---------| | Earnings | analyze_earnings_surprise() | EarningsSurprise | | Fundamentals | analyze_fundamentals() | Fundamentals | | Analysts | analyze_analyst_sentiment() | AnalystSentiment | | Historical | analyze_historical_patterns() | HistoricalPatterns | | Market | analyze_market_context() | MarketContext | | Sector | analyze_sector_performance() | SectorComparison | | Momentum | analyze_momentum() | MomentumAnalysis | | Sentiment | analyze_sentiment() | SentimentAnalysis |

3. Sentiment Sub-Analyzers

Sentiment runs 5 parallel async tasks:

results = await asyncio.gather(
    get_fear_greed_index(),      # CNN Fear & Greed
    get_short_interest(data),    # Yahoo Finance
    get_vix_term_structure(),    # VIX Futures
    get_insider_activity(),      # SEC EDGAR
    get_put_call_ratio(data),    # Options Chain
    return_exceptions=True
)

Timeout: 10 seconds per indicator Minimum: 2 of 5 indicators required

4. Signal Synthesis

def synthesize_signal(
    ticker, company_name,
    earnings, fundamentals, analysts, historical,
    market_context, sector, earnings_timing,
    momentum, sentiment,
    breaking_news, geopolitical_risk_warning, geopolitical_risk_penalty
) -> Signal:

Scoring:

1. Collect available component scores
2. Apply normalized weights
3. Calculate weighted average → final_score
4. Apply adjustments (timing, overbought, risk-off)
5. Determine recommendation threshold

Thresholds:

if final_score > 0.33:
    recommendation = "BUY"
elif final_score < -0.33:
    recommendation = "SELL"
else:
    recommendation = "HOLD"

---

Caching Strategy

What's Cached

| Data | TTL | Key | |------|-----|-----| | Market Context | 1 hour | market_context | | Fear & Greed | 1 hour | fear_greed | | VIX Structure | 1 hour | vix_structure | | Breaking News | 1 hour | breaking_news |

Cache Implementation

_SENTIMENT_CACHE = {}
_CACHE_TTL_SECONDS = 3600  # 1 hour

def _get_cached(key: str):
    if key in _SENTIMENT_CACHE:
        value, timestamp = _SENTIMENT_CACHE[key]
        if time.time() - timestamp < _CACHE_TTL_SECONDS:
            return value
    return None

def _set_cache(key: str, value):
    _SENTIMENT_CACHE[key] = (value, time.time())

Why This Matters

• First stock: ~8 seconds (full fetch)
• Second stock: ~4 seconds (reuses market data)
• Same stock again: ~4 seconds (no stock-level cache)

---

Data Flow

Single Stock Analysis

User Input: "AAPL"
     │
     ▼
┌─────────────────────────────────────────────────────────────┐
│ 1. FETCH DATA (yfinance)                                    │
│    - Stock info, earnings, price history                    │
│    - ~2 seconds                                             │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. PARALLEL ANALYSIS                                        │
│                                                             │
│    ┌──────────┐ ┌──────────┐ ┌──────────┐                  │
│    │ Earnings │ │Fundmtls  │ │ Analysts │  ... (sync)      │
│    └──────────┘ └──────────┘ └──────────┘                  │
│                                                             │
│    ┌────────────────────────────────────┐                  │
│    │ Market Context (cached or fetch)   │  ~1 second       │
│    └────────────────────────────────────┘                  │
│                                                             │
│    ┌────────────────────────────────────┐                  │
│    │ Sentiment (5 async tasks)          │  ~3-5 seconds    │
│    │  - Fear/Greed (cached)             │                  │
│    │  - Short Interest                  │                  │
│    │  - VIX Structure (cached)          │                  │
│    │  - Insider Trading (slow!)         │                  │
│    │  - Put/Call Ratio                  │                  │
│    └────────────────────────────────────┘                  │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. SYNTHESIZE SIGNAL                                        │
│    - Combine scores with weights                            │
│    - Apply adjustments                                      │
│    - Generate caveats                                       │
│    - ~10 ms                                                 │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. OUTPUT                                                   │
│    - Text or JSON format                                    │
│    - Include disclaimer                                     │
└─────────────────────────────────────────────────────────────┘

---

Risk Detection

Geopolitical Risk

GEOPOLITICAL_RISK_MAP = {
    "taiwan": {
        "keywords": ["taiwan", "tsmc", "strait"],
        "sectors": ["Technology", "Communication Services"],
        "affected_tickers": ["NVDA", "AMD", "TSM", ...],
        "impact": "Semiconductor supply chain disruption",
    },
    # ... china, russia_ukraine, middle_east, banking_crisis
}

Process:

1. Check breaking news for keywords
2. If keyword found, check if ticker in affected list
3. Apply confidence penalty (30% direct, 15% sector)

Breaking News

def check_breaking_news(verbose: bool = False) -> list[str] | None:
    """Scan Google News RSS for crisis keywords (last 24h)."""

Crisis Keywords:

CRISIS_KEYWORDS = {
    "war": ["war", "invasion", "military strike", ...],
    "economic": ["recession", "crisis", "collapse", ...],
    "regulatory": ["sanctions", "embargo", "ban", ...],
    "disaster": ["earthquake", "hurricane", "pandemic", ...],
    "financial": ["emergency rate", "bailout", ...],
}

---

File Structure

stock-analysis/
├── scripts/
│   ├── analyze_stock.py      # Main analysis engine (2500+ lines)
│   ├── portfolio.py          # Portfolio management
│   ├── dividends.py          # Dividend analysis
│   ├── watchlist.py          # Watchlist + alerts
│   └── test_stock_analysis.py # Unit tests
├── docs/
│   ├── CONCEPT.md            # Philosophy & ideas
│   ├── USAGE.md              # Practical guide
│   └── ARCHITECTURE.md       # This file
├── SKILL.md                  # OpenClaw skill definition
├── README.md                 # Project overview
└── .clawdhub/                # ClawHub metadata

---

Data Storage

Portfolio (portfolios.json)

{
  "portfolios": [
    {
      "name": "Retirement",
      "created_at": "2024-01-01T00:00:00Z",
      "assets": [
        {
          "ticker": "AAPL",
          "quantity": 100,
          "cost_basis": 150.00,
          "type": "stock",
          "added_at": "2024-01-01T00:00:00Z"
        }
      ]
    }
  ]
}

Watchlist (watchlist.json)

[
  {
    "ticker": "NVDA",
    "added_at": "2024-01-15T10:30:00Z",
    "price_at_add": 700.00,
    "target_price": 800.00,
    "stop_price": 600.00,
    "alert_on_signal": true,
    "last_signal": "BUY",
    "last_check": "2024-01-20T08:00:00Z"
  }
]

---

Dependencies

# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "yfinance>=0.2.40",      # Stock data
#     "pandas>=2.0.0",         # Data manipulation
#     "fear-and-greed>=0.4",   # CNN Fear & Greed
#     "edgartools>=2.0.0",     # SEC EDGAR filings
#     "feedparser>=6.0.0",     # RSS parsing
# ]
# ///

Why These:

• yfinance: Most reliable free stock API
• pandas: Industry standard for financial data
• fear-and-greed: Simple CNN F&G wrapper
• edgartools: Clean SEC EDGAR access
• feedparser: Robust RSS parsing

---

Performance Optimization

Current

| Operation | Time | |-----------|------| | yfinance fetch | ~2s | | Market context | ~1s (cached after) | | Insider trading | ~3-5s (slowest!) | | Sentiment (parallel) | ~3-5s | | Synthesis | ~10ms | | Total | 5-10s |

Fast Mode (--fast)

Skips:

• Insider trading (SEC EDGAR)
• Breaking news scan

Result: 2-3 seconds

Future Optimizations

1. Stock-level caching — Cache fundamentals for 24h
2. Batch API calls — yfinance supports multiple tickers
3. Background refresh — Pre-fetch watchlist data
4. Local SEC data — Avoid EDGAR API calls

---

Error Handling

Retry Strategy

max_retries = 3
for attempt in range(max_retries):
    try:
        # fetch data
    except Exception as e:
        wait_time = 2 ** attempt  # Exponential backoff: 1, 2, 4 seconds
        time.sleep(wait_time)

Graceful Degradation

• Missing earnings → Skip dimension, reweight
• Missing analysts → Skip dimension, reweight
• Missing sentiment → Skip dimension, reweight
• API failure → Return None, continue with partial data

Minimum Requirements

• At least 2 of 8 dimensions required
• At least 2 of 5 sentiment indicators required
• Otherwise → HOLD with low confidence

File v6.2.0:docs/CONCEPT.md

Concept & Philosophy

The Problem

Making investment decisions is hard. There's too much data, too many opinions, and too much noise. Most retail investors either:

1. Over-simplify — Buy based on headlines or tips
2. Over-complicate — Get lost in endless research
3. Freeze — Analysis paralysis, never act

The Solution

Stock Analysis provides a structured, multi-dimensional framework that:

• Aggregates data from multiple sources
• Weighs different factors objectively
• Produces a clear BUY / HOLD / SELL signal
• Explains the reasoning with bullet points
• Flags risks and caveats

Think of it as a second opinion — not a replacement for your judgment, but a systematic check.

---

Core Philosophy

1. Multiple Perspectives Beat Single Metrics

No single metric tells the whole story:

• A low P/E might mean "cheap" or "dying business"
• High analyst ratings might mean "priced in" or "genuine upside"
• Strong momentum might mean "trend" or "overbought"

By combining 8 dimensions, we get a more complete picture.

2. Contrarian Signals Matter

Some of our best signals are contrarian:

| Indicator | Crowd Says | We Interpret | |-----------|------------|--------------| | Extreme Fear (Fear & Greed < 25) | "Sell everything!" | Potential buy opportunity | | Extreme Greed (> 75) | "Easy money!" | Caution, reduce exposure | | High Short Interest + Days to Cover | "Stock is doomed" | Squeeze potential | | Insider Buying | (often ignored) | Smart money signal |

3. Timing Matters

A good stock at the wrong time is a bad trade:

• Pre-earnings — Even strong stocks can gap down 10%+
• Post-spike — Buying after a 20% run often means buying the top
• Overbought — RSI > 70 + near 52-week high = high-risk entry

We detect these timing issues and adjust recommendations accordingly.

4. Context Changes Everything

The same stock behaves differently in different market regimes:

| Regime | Characteristics | Impact | |--------|-----------------|--------| | Bull | VIX < 20, SPY up | BUY signals more reliable | | Bear | VIX > 30, SPY down | Even good stocks fall | | Risk-Off | GLD/TLT/UUP rising | Flight to safety, reduce equity | | Geopolitical | Crisis keywords | Sector-specific penalties |

5. Dividends Are Different

Income investors have different priorities than growth investors:

| Growth Investor | Income Investor | |-----------------|-----------------| | Price appreciation | Dividend yield | | Revenue growth | Payout sustainability | | Market share | Dividend growth rate | | P/E ratio | Safety of payment |

That's why we have a separate dividend analysis module.

---

The 8 Dimensions

Why These 8?

Each dimension captures a different aspect of investment quality:

┌─────────────────────────────────────────────────────────────┐
│                    FUNDAMENTAL VALUE                         │
│  ┌─────────────────┐  ┌─────────────────┐                   │
│  │    Earnings     │  │  Fundamentals   │                   │
│  │    Surprise     │  │   (P/E, etc.)   │                   │
│  │     (30%)       │  │     (20%)       │                   │
│  └─────────────────┘  └─────────────────┘                   │
├─────────────────────────────────────────────────────────────┤
│                    EXTERNAL VALIDATION                       │
│  ┌─────────────────┐  ┌─────────────────┐                   │
│  │    Analyst      │  │   Historical    │                   │
│  │   Sentiment     │  │    Patterns     │                   │
│  │     (20%)       │  │     (10%)       │                   │
│  └─────────────────┘  └─────────────────┘                   │
├─────────────────────────────────────────────────────────────┤
│                    MARKET ENVIRONMENT                        │
│  ┌─────────────────┐  ┌─────────────────┐                   │
│  │    Market       │  │     Sector      │                   │
│  │    Context      │  │  Performance    │                   │
│  │     (10%)       │  │     (15%)       │                   │
│  └─────────────────┘  └─────────────────┘                   │
├─────────────────────────────────────────────────────────────┤
│                    TECHNICAL & SENTIMENT                     │
│  ┌─────────────────┐  ┌─────────────────┐                   │
│  │    Momentum     │  │   Sentiment     │                   │
│  │  (RSI, range)   │  │ (Fear, shorts)  │                   │
│  │     (15%)       │  │     (10%)       │                   │
│  └─────────────────┘  └─────────────────┘                   │
└─────────────────────────────────────────────────────────────┘

Weight Rationale

| Weight | Dimension | Rationale | |--------|-----------|-----------| | 30% | Earnings | Most direct measure of company performance | | 20% | Fundamentals | Long-term value indicators | | 20% | Analysts | Professional consensus (with skepticism) | | 15% | Sector | Relative performance matters | | 15% | Momentum | Trend is your friend (until it isn't) | | 10% | Market | Rising tide lifts all boats | | 10% | Sentiment | Contrarian edge | | 10% | Historical | Past behavior predicts future reactions |

Note: Weights auto-normalize when data is missing.

---

Risk Detection Philosophy

"Don't Lose Money"

Warren Buffett's Rule #1. Our risk detection is designed to prevent bad entries:

1. Pre-Earnings Hold — Don't buy right before a binary event
2. Post-Spike Caution — Don't chase a run-up
3. Overbought Warning — Technical exhaustion
4. Risk-Off Mode — When even good stocks fall
5. Geopolitical Flags — Sector-specific event risk

False Positive vs False Negative

We err on the side of caution:

• Missing a 10% gain is annoying
• Catching a 30% loss is devastating

That's why our caveats are prominent, and we downgrade BUY → HOLD liberally.

---

Crypto Adaptation

Crypto is fundamentally different from stocks:

| Stocks | Crypto | |--------|--------| | Earnings | No earnings | | P/E Ratio | Market cap tiers | | Sector ETFs | BTC correlation | | Dividends | Staking yields (not tracked) | | SEC Filings | No filings |

We adapted the framework:

• 3 dimensions instead of 8
• BTC correlation as a key metric
• Category classification (L1, DeFi, etc.)
• No sentiment (no insider data for crypto)

---

Why Not Just Use [X]?

vs. Stock Screeners (Finviz, etc.)

• Screeners show data, we provide recommendations
• We combine fundamental + technical + sentiment
• We flag timing and risk issues

vs. Analyst Reports

• Analysts have conflicts of interest
• Reports are often stale
• We aggregate multiple signals

vs. Trading Bots

• Bots execute, we advise
• We explain reasoning
• Human stays in control

vs. ChatGPT/AI Chat

• We have structured scoring, not just conversation
• Real-time data fetching
• Consistent methodology

---

Limitations We Acknowledge

1. Data Lag — Yahoo Finance is 15-20 min delayed
2. US Focus — International stocks have incomplete data
3. No Execution — We advise, you decide and execute
4. Past ≠ Future — All models have limits
5. Black Swans — Can't predict unpredictable events

This is a tool, not a crystal ball.

---

The Bottom Line

Stock Analysis v6.0 is designed to be your systematic second opinion:

• ✅ Multi-dimensional analysis
• ✅ Clear recommendations
• ✅ Risk detection
• ✅ Explained reasoning
• ✅ Fast and automated

NOT:

• ❌ Financial advice
• ❌ Guaranteed returns
• ❌ Replacement for research
• ❌ Trading signals

Use it wisely. 📈

File v6.2.0:docs/HOT_SCANNER.md

🔥 Hot Scanner

Find viral stocks & crypto trends in real-time by aggregating multiple data sources.

Overview

The Hot Scanner answers one question: "What's hot right now?"

It aggregates data from:

• CoinGecko (trending coins, biggest movers)
• Google News (finance & crypto headlines)
• Yahoo Finance (gainers, losers, most active)
• Twitter/X (social sentiment, optional)

Quick Start

# Full scan with all sources
python3 scripts/hot_scanner.py

# Skip social media (faster)
python3 scripts/hot_scanner.py --no-social

# JSON output for automation
python3 scripts/hot_scanner.py --json

Output Format

Console Output

============================================================
🔥 HOT SCANNER v2 - What's Trending Right Now?
📅 2026-02-02 10:45:30 UTC
============================================================

📊 TOP TRENDING (by buzz):
   1. BTC      (6 pts) [CoinGecko, Google News] 📉 bearish (-2.5%)
   2. ETH      (5 pts) [CoinGecko, Twitter] 📉 bearish (-7.2%)
   3. NVDA     (3 pts) [Google News, Yahoo] 📰 Earnings beat...

🪙 CRYPTO HIGHLIGHTS:
   🚀 RIVER    River              +14.0%
   📉 BTC      Bitcoin             -2.5%
   📉 ETH      Ethereum            -7.2%

📈 STOCK MOVERS:
   🟢 NVDA (gainers)
   🔴 TSLA (losers)
   📊 AAPL (most active)

🐦 SOCIAL BUZZ:
   [twitter] Bitcoin to $100k prediction...
   [reddit_wsb] GME yolo update...

📰 BREAKING NEWS:
   [BTC, ETH] Crypto crash: $2.5B liquidated...
   [NVDA] Nvidia beats earnings expectations...

JSON Output

{
  "scan_time": "2026-02-02T10:45:30+00:00",
  "top_trending": [
    {
      "symbol": "BTC",
      "mentions": 6,
      "sources": ["CoinGecko Trending", "Google News"],
      "signals": ["📉 bearish (-2.5%)"]
    }
  ],
  "crypto_highlights": [...],
  "stock_highlights": [...],
  "social_buzz": [...],
  "breaking_news": [...]
}

Data Sources

CoinGecko (No Auth Required)

| Endpoint | Data | |----------|------| | /search/trending | Top 15 trending coins | | /coins/markets | Top 100 by market cap with 24h changes |

Scoring: Trending coins get 2 points, movers with >3% change get 1 point.

Google News RSS (No Auth Required)

| Feed | Content | |------|---------| | Business News | General finance headlines | | Crypto Search | Bitcoin, Ethereum, crypto keywords |

Ticker Extraction: Uses regex patterns and company name mappings.

Yahoo Finance (No Auth Required)

| Page | Data | |------|------| | /gainers | Top gaining stocks | | /losers | Top losing stocks | | /most-active | Highest volume stocks |

Note: Requires gzip decompression.

Twitter/X (Auth Required)

Uses bird CLI for Twitter search.

Searches:

• stock OR $SPY OR $QQQ OR earnings
• bitcoin OR ethereum OR crypto OR $BTC

Twitter/X Setup

1. Install bird CLI

# macOS
brew install steipete/tap/bird

# npm
npm install -g @steipete/bird

2. Get Auth Tokens

Option A: Browser cookies (macOS)

1. Login to x.com in Safari/Chrome
2. Grant Terminal "Full Disk Access" in System Settings
3. Run bird whoami to verify

Option B: Manual extraction

1. Open x.com in Chrome
2. DevTools (F12) → Application → Cookies → x.com
3. Copy auth_token and ct0 values

3. Configure

Create .env file in the skill directory:

# /path/to/stock-analysis/.env
AUTH_TOKEN=your_auth_token_here
CT0=your_ct0_token_here

Or export as environment variables:

export AUTH_TOKEN="..."
export CT0="..."

4. Verify

bird whoami
# Should show: 🙋 @YourUsername

Scoring System

Each mention from a source adds points:

| Source | Points | |--------|--------| | CoinGecko Trending | 2 | | CoinGecko Movers | 1 | | Google News | 1 | | Yahoo Finance | 1 | | Twitter/X | 1 | | Reddit (high score) | 2 | | Reddit (normal) | 1 |

Symbols are ranked by total points across all sources.

Ticker Extraction

Patterns

# Cashtag: $AAPL
r'\$([A-Z]{1,5})\b'

# Parentheses: (AAPL)
r'\(([A-Z]{2,5})\)'

# Stock mentions: AAPL stock, AAPL shares
r'\b([A-Z]{2,5})(?:\'s|:|\s+stock|\s+shares)'

Company Mappings

{
    "Apple": "AAPL",
    "Microsoft": "MSFT",
    "Tesla": "TSLA",
    "Nvidia": "NVDA",
    "Bitcoin": "BTC",
    "Ethereum": "ETH",
    # ... etc
}

Crypto Keywords

{
    "bitcoin": "BTC",
    "ethereum": "ETH",
    "solana": "SOL",
    "dogecoin": "DOGE",
    # ... etc
}

Automation

Cron Job

# Daily at 8 AM
0 8 * * * cd /path/to/stock-analysis && python3 scripts/hot_scanner.py --json > cache/daily_scan.json

OpenClaw Integration

# Cron job config
name: "🔥 Daily Hot Scanner"
schedule:
  kind: cron
  expr: "0 8 * * *"
  tz: "Europe/Berlin"
payload:
  kind: agentTurn
  message: "Run hot scanner and summarize results"
  deliver: true
sessionTarget: isolated

Caching

Results are saved to:

• cache/hot_scan_latest.json — Most recent scan

Limitations

• Reddit: Blocked without OAuth (403). Requires API application.
• Twitter: Requires auth tokens, may expire.
• Yahoo: Sometimes rate-limited.
• Google News: RSS URLs may change.

Future Enhancements

• [ ] Reddit API integration (PRAW)
• [ ] StockTwits integration
• [ ] Google Trends
• [ ] Historical trend tracking
• [ ] Alert thresholds (notify when score > X)

Troubleshooting

Twitter not working

# Check auth
bird whoami

# Should see your username
# If not, re-export tokens

Yahoo 403 or gzip errors

The scanner handles gzip automatically. If issues persist, Yahoo may be rate-limiting.

No tickers found

Check that news headlines contain recognizable patterns. The scanner uses conservative extraction to avoid false positives.

File v6.2.0:docs/USAGE.md

Usage Guide

Practical examples for using Stock Analysis v6.0 in real scenarios.

Table of Contents

1. Basic Stock Analysis
2. Comparing Stocks
3. Crypto Analysis
4. Dividend Investing
5. Portfolio Management
6. Watchlist & Alerts
7. Performance Tips
8. Interpreting Results

---

Basic Stock Analysis

Single Stock

uv run scripts/analyze_stock.py AAPL

Output:

===========================================================================
STOCK ANALYSIS: AAPL (Apple Inc.)
Generated: 2024-02-01T10:30:00
===========================================================================

RECOMMENDATION: BUY (Confidence: 72%)

SUPPORTING POINTS:
• Beat by 8.2% - EPS $2.18 vs $2.01 expected
• Strong margin: 24.1%
• Analyst consensus: Buy with 12.3% upside (42 analysts)
• Momentum: RSI 58 (neutral)
• Sector: Technology uptrend (+5.2% 1m)

CAVEATS:
• Earnings in 12 days - high volatility expected
• High market volatility (VIX 24)

===========================================================================
DISCLAIMER: NOT FINANCIAL ADVICE.
===========================================================================

JSON Output

For programmatic use:

uv run scripts/analyze_stock.py AAPL --output json | jq '.recommendation, .confidence'

Verbose Mode

See what's happening under the hood:

uv run scripts/analyze_stock.py AAPL --verbose

---

Comparing Stocks

Side-by-Side Analysis

uv run scripts/analyze_stock.py AAPL MSFT GOOGL

Each stock gets a full analysis. Compare recommendations and confidence levels.

Sector Comparison

Compare stocks in the same sector:

# Banks
uv run scripts/analyze_stock.py JPM BAC WFC GS

# Tech
uv run scripts/analyze_stock.py AAPL MSFT GOOGL AMZN META

---

Crypto Analysis

Basic Crypto

uv run scripts/analyze_stock.py BTC-USD

Crypto-Specific Output:

• Market cap classification (large/mid/small)
• Category (Smart Contract L1, DeFi, etc.)
• BTC correlation (30-day)
• Momentum (RSI, price range)

Compare Cryptos

uv run scripts/analyze_stock.py BTC-USD ETH-USD SOL-USD

Supported Cryptos

BTC, ETH, BNB, SOL, XRP, ADA, DOGE, AVAX, DOT, MATIC,
LINK, ATOM, UNI, LTC, BCH, XLM, ALGO, VET, FIL, NEAR

Use -USD suffix: BTC-USD, ETH-USD, etc.

---

Dividend Investing

Analyze Dividend Stock

uv run scripts/dividends.py JNJ

Output:

============================================================
DIVIDEND ANALYSIS: JNJ (Johnson & Johnson)
============================================================

Current Price:    $160.50
Annual Dividend:  $4.76
Dividend Yield:   2.97%
Payment Freq:     quarterly
Ex-Dividend:      2024-02-15

Payout Ratio:     65.0% (moderate)
5Y Div Growth:    +5.8%
Consecutive Yrs:  62

SAFETY SCORE:     78/100
INCOME RATING:    GOOD

Safety Factors:
  • Moderate payout ratio (65%)
  • Good dividend growth (+5.8% CAGR)
  • Dividend Aristocrat (62+ years)

Dividend History:
  2023: $4.52
  2022: $4.36
  2021: $4.24
  2020: $4.04
  2019: $3.80
============================================================

Compare Dividend Stocks

uv run scripts/dividends.py JNJ PG KO MCD VZ T

Dividend Aristocrats Screen

Look for stocks with:

• Yield > 2%
• Payout < 60%
• Growth > 5%
• Consecutive years > 25

---

Portfolio Management

Create Portfolio

uv run scripts/portfolio.py create "Retirement"

Add Holdings

# Stocks
uv run scripts/portfolio.py add AAPL --quantity 100 --cost 150.00

# Crypto
uv run scripts/portfolio.py add BTC-USD --quantity 0.5 --cost 40000

View Portfolio

uv run scripts/portfolio.py show

Output:

Portfolio: Retirement
====================

Assets:
  AAPL     100 shares @ $150.00 = $15,000.00
           Current: $185.00 = $18,500.00 (+23.3%)
  
  BTC-USD  0.5 @ $40,000 = $20,000.00
           Current: $45,000 = $22,500.00 (+12.5%)

Total Cost:    $35,000.00
Current Value: $41,000.00
Total P&L:     +$6,000.00 (+17.1%)

Analyze Portfolio

# Full analysis of all holdings
uv run scripts/analyze_stock.py --portfolio "Retirement"

# With period returns
uv run scripts/analyze_stock.py --portfolio "Retirement" --period monthly

Rebalance Check

The analysis flags concentration warnings:

⚠️ CONCENTRATION WARNINGS:
   • AAPL: 45.1% (>30% of portfolio)

---

Watchlist & Alerts

Add to Watchlist

# Basic watch
uv run scripts/watchlist.py add NVDA

# With price target
uv run scripts/watchlist.py add NVDA --target 800

# With stop loss
uv run scripts/watchlist.py add NVDA --stop 600

# Alert on signal change
uv run scripts/watchlist.py add NVDA --alert-on signal

# All options
uv run scripts/watchlist.py add NVDA --target 800 --stop 600 --alert-on signal

View Watchlist

uv run scripts/watchlist.py list

Output:

{
  "success": true,
  "items": [
    {
      "ticker": "NVDA",
      "current_price": 725.50,
      "price_at_add": 700.00,
      "change_pct": 3.64,
      "target_price": 800.00,
      "to_target_pct": 10.27,
      "stop_price": 600.00,
      "to_stop_pct": -17.30,
      "alert_on_signal": true,
      "last_signal": "BUY",
      "added_at": "2024-01-15"
    }
  ],
  "count": 1
}

Check Alerts

# Check for triggered alerts
uv run scripts/watchlist.py check

# Format for notification (Telegram)
uv run scripts/watchlist.py check --notify

Alert Example:

📢 Stock Alerts

🎯 NVDA hit target! $802.50 >= $800.00
🛑 TSLA hit stop! $195.00 <= $200.00
📊 AAPL signal changed: HOLD → BUY

Remove from Watchlist

uv run scripts/watchlist.py remove NVDA

---

Performance Tips

Fast Mode

Skip slow analyses for quick checks:

# Skip insider trading + breaking news
uv run scripts/analyze_stock.py AAPL --fast

Speed comparison: | Mode | Time | What's Skipped | |------|------|----------------| | Default | 5-10s | Nothing | | --no-insider | 3-5s | SEC EDGAR | | --fast | 2-3s | Insider + News |

Batch Analysis

Analyze multiple stocks in one command:

uv run scripts/analyze_stock.py AAPL MSFT GOOGL AMZN META

Caching

Market context is cached for 1 hour:

• VIX, SPY, QQQ trends
• Fear & Greed Index
• VIX term structure
• Breaking news

Second analysis of different stock reuses cached data.

---

Interpreting Results

Recommendation Thresholds

| Score | Recommendation | |-------|----------------| | > +0.33 | BUY | | -0.33 to +0.33 | HOLD | | < -0.33 | SELL |

Confidence Levels

| Confidence | Meaning | |------------|---------| | > 80% | Strong conviction | | 60-80% | Moderate conviction | | 40-60% | Mixed signals | | < 40% | Low conviction |

Reading Caveats

Always read the caveats! They often contain critical information:

CAVEATS:
• Earnings in 5 days - high volatility expected    ← Timing risk
• RSI 78 (overbought) + near 52w high              ← Technical risk
• ⚠️ BREAKING NEWS: Fed emergency rate discussion  ← External risk
• ⚠️ SECTOR RISK: China tensions affect tech       ← Geopolitical

When to Ignore the Signal

• Pre-earnings: Even BUY → wait until after
• Overbought: Consider smaller position
• Risk-off: Reduce overall exposure
• Low confidence: Do more research

When to Trust the Signal

• High confidence + no major caveats
• Multiple supporting points align
• Sector is strong
• Market regime is favorable

---

Common Workflows

Morning Check

# Check watchlist alerts
uv run scripts/watchlist.py check --notify

# Quick portfolio update
uv run scripts/analyze_stock.py --portfolio "Main" --fast

Research New Stock

# Full analysis
uv run scripts/analyze_stock.py XYZ

# If dividend stock
uv run scripts/dividends.py XYZ

# Add to watchlist for monitoring
uv run scripts/watchlist.py add XYZ --alert-on signal

Weekly Review

# Full portfolio analysis
uv run scripts/analyze_stock.py --portfolio "Main" --period weekly

# Check dividend holdings
uv run scripts/dividends.py JNJ PG KO

---

Troubleshooting

"Invalid ticker"

• Check spelling
• For crypto, use -USD suffix
• Non-US stocks may not work

"Insufficient data"

• Stock might be too new
• ETFs have limited data
• OTC stocks often fail

Slow Performance

• Use --fast for quick checks
• Insider trading is slowest
• Breaking news adds ~2s

Missing Data

• Not all stocks have analyst coverage
• Some metrics require options chains
• Crypto has no sentiment data

File v6.2.0:skill-card.md

Description: <br>

Analyzes stocks and cryptocurrencies with Yahoo Finance data, portfolio and watchlist tracking, dividend metrics, stock scoring, trend detection, and rumor scanning. <br>

This skill is ready for commercial/non-commercial use. <br>

Publisher: <br>

udiedrichsen <br>

License/Terms of Use: <br>

Use Case: <br>

External users and developers use this skill to run command-line stock, crypto, dividend, portfolio, watchlist, trend, and rumor analyses for informational market research. <br>

Deployment Geography for Use: <br>

Global <br>

Known Risks and Mitigations: <br>

Risk: Optional Twitter/X scanning can expose live AUTH_TOKEN and CT0 session credentials to an external CLI. <br> Mitigation: Use finance-only commands or run the hot scanner with --no-social unless social-media data is required; do not provide AUTH_TOKEN or CT0 unless the credential exposure is acceptable. <br> Risk: The Twitter/X setup may require broad local permissions such as Terminal Full Disk Access. <br> Mitigation: Avoid granting broad local permissions casually, and keep any .env file containing session credentials out of shared folders and repositories. <br> Risk: Market, short-interest, filing, news, and social signals may be delayed, cached, rate-limited, or keyword-based. <br> Mitigation: Treat outputs as informational market research, verify important claims against primary sources, and do not use the skill as financial advice. <br>

Reference(s): <br>

• ClawHub Skill Page <br>
• Yahoo Finance <br>
• Stock Analysis README <br>
• Usage Guide <br>
• Hot Scanner Documentation <br>
• Architecture Notes <br>

Skill Output: <br>

Output Type(s): [Text, JSON, Shell commands, Configuration, Guidance] <br> Output Format: [Console text and optional JSON, with command examples and local configuration guidance] <br> Output Parameters: [1D] <br> Other Properties Related to Output: [May write local portfolio, watchlist, and scanner cache JSON files under user or skill storage paths.] <br>

Skill Version(s): <br>

6.2.0 (source: frontmatter and server release metadata) <br>

Ethical Considerations: <br>

Users should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>

File v6.2.0:TODO.md

Stock Analysis - Future Enhancements

Roadmap Overview

v4.0.0 (Current) - Geopolitical Risk & News Sentiment

✅ 8 analysis dimensions with Fear/Greed, short interest, VIX structure, put/call ratio ✅ Safe-haven indicators (GLD, TLT, UUP) with risk-off detection ✅ Breaking news alerts via Google News RSS ✅ Geopolitical risk mapping (Taiwan, China, Russia, Middle East, Banking) ✅ Sector-specific crisis flagging with confidence penalties ✅ 1h caching for shared indicators (Fear/Greed, VIX structure, breaking news) ✅ Async parallel sentiment fetching (5 indicators with 10s timeouts)

v5.0.0 (Current) - Portfolio & Crypto

✅ Portfolio management (create, add, remove, show assets) ✅ Cryptocurrency support (Top 20 by market cap) ✅ Portfolio analysis with --portfolio flag ✅ Periodic returns (--period daily/weekly/monthly/quarterly/yearly) ✅ Concentration warnings (>30% single asset) ✅ Crypto fundamentals (market cap, category, BTC correlation)

v4.1.0 - Performance & Completeness

✅ Full insider trading parsing via edgartools (Task #1) ✅ Market context caching with 1h TTL (Task #3b) 🔧 SEC EDGAR rate limit monitoring (Task #4 - low priority)

Future (v6.0+)

💡 Research phase: Social sentiment, fund flows, on-chain metrics

---

Sentiment Analysis Improvements

1. Implement Full Insider Trading Parsing

Status: ✅ DONE Priority: Medium Effort: 2-3 hours

Current State:

• ✅ get_insider_activity() fetches Form 4 filings via edgartools
• ✅ SEC identity configured ([email protected])
• ✅ Aggregates buys/sells over 90-day window
• ✅ Scoring logic: strong buying (+0.8), moderate (+0.4), neutral (0), moderate selling (-0.4), strong (-0.8)

Tasks:

• [ ] Research edgartools API for Form 4 parsing
• [ ] Implement transaction aggregation (90-day window)
• [ ] Calculate net shares bought/sold
• [ ] Calculate net value in millions USD
• [ ] Apply scoring logic:
  • Strong buying (>100K shares or >$1M): +0.8
  • Moderate buying (>10K shares or >$0.1M): +0.4
  • Neutral: 0
  • Moderate selling: -0.4
  • Strong selling: -0.8
• [ ] Add error handling for missing/incomplete filings
• [ ] Test with multiple tickers (BAC, TSLA, AAPL)
• [ ] Verify SEC rate limit compliance (10 req/s)

Expected Impact:

• Insider activity detection for 4th sentiment indicator
• Increase from 3/5 to 4/5 indicators typically available

---

2. Add Parallel Async Fetching

Status: ✅ DONE (sentiment indicators) Priority: High Effort: 4-6 hours

Current State:

• ✅ Sentiment indicators fetched in parallel via asyncio.gather()
• ✅ 10s timeout per indicator
• Main data fetches (yfinance) still sequential (acceptable)

Tasks:

• [ ] Convert sentiment helper functions to async
  • [ ] async def get_fear_greed_index()
  • [ ] async def get_short_interest(data)
  • [ ] async def get_vix_term_structure()
  • [ ] async def get_insider_activity(ticker)
  • [ ] async def get_put_call_ratio(data)
• [ ] Update analyze_sentiment() to use asyncio.gather()
• [ ] Handle yfinance thread safety (may need locks)
• [ ] Add timeout per indicator (10s max)
• [ ] Test with multiple stocks in sequence
• [ ] Measure actual runtime improvement
• [ ] Update SKILL.md with new runtime (target: 3-4s)

Expected Impact:

• Reduce runtime from 6-10s to 3-4s per stock
• Better user experience for multi-stock analysis

---

3. Add Caching for Shared Indicators

Status: ✅ DONE (sentiment + breaking news) Priority: Medium Effort: 2-3 hours

Current State:

• ✅ Fear & Greed Index cached (1h TTL)
• ✅ VIX term structure cached (1h TTL)
• ✅ Breaking news cached (1h TTL)
• ✅ Market context (VIX/SPY/QQQ/GLD/TLT/UUP) cached (1h TTL)

Tasks:

• [ ] Design cache structure (simple dict or functools.lru_cache)
• [ ] Implement TTL (time-to-live):
  • Fear & Greed: 1 hour
  • VIX structure: 1 hour
  • Short interest: No cache (per-stock)
  • Insider activity: No cache (per-stock)
  • Put/Call ratio: No cache (per-stock)
• [ ] Add cache invalidation logic
• [ ] Add verbose logging for cache hits/misses
• [ ] Test multi-stock analysis (e.g., BAC TSLA AAPL)
• [ ] Measure performance improvement
• [ ] Document caching behavior in SKILL.md

Expected Impact:

• Multi-stock analysis faster (e.g., 3 stocks: 18-30s → 10-15s)
• Reduced API calls to Fear/Greed and VIX data sources
• Same-session analysis efficiency

---

4. Monitor SEC EDGAR Rate Limits

Status: Not Started Priority: Low (until insider trading implemented) Effort: 1-2 hours

Current State:

• SEC EDGAR API has 10 requests/second rate limit
• No rate limit tracking or logging
• edgartools may handle rate limiting internally

Tasks:

• [ ] Research edgartools rate limit handling
• [ ] Add request counter/tracker if needed
• [ ] Implement exponential backoff on 429 errors
• [ ] Add logging for rate limit hits
• [ ] Test with high-volume scenarios (10+ stocks in quick succession)
• [ ] Document rate limit behavior
• [ ] Add error message if rate limited: "SEC API rate limited, try again in 1 minute"

Expected Impact:

• Robust handling of SEC API limits in production
• Clear user feedback if limits hit
• Prevent API blocking/banning

---

Stock Analysis 4.0: Geopolitical Risk & News Sentiment

What's Currently Missing

The current implementation captures:

• ✅ VIX (general market fear)
• ✅ SPY/QQQ trends (market direction)
• ✅ Sector performance

What we don't have yet:

• ❌ Geopolitical risk indicators
• ❌ News sentiment analysis
• ❌ Sector-specific crisis flags

---

7. Geopolitical Risk Index

Status: ✅ DONE (keyword-based) Priority: High Effort: 8-12 hours

Proposed Approach: Option A: Use GPRD (Geopolitical Risk Daily Index) from policyuncertainty.com Option B: Scan news APIs (NewsAPI, GDELT) for geopolitical keywords

Tasks:

• [ ] Research free geopolitical risk data sources
  • [ ] Check policyuncertainty.com API availability
  • [ ] Evaluate NewsAPI free tier limits
  • [ ] Consider GDELT Project (free, comprehensive)
• [ ] Design risk scoring system (0-100 scale)
• [ ] Implement data fetching with caching (4-hour TTL)
• [ ] Map risk levels to sentiment scores:
  • Low risk (0-30): +0.2 (bullish)
  • Moderate risk (30-60): 0 (neutral)
  • High risk (60-80): -0.3 (caution)
  • Extreme risk (80-100): -0.5 (bearish)
• [ ] Add to sentiment analysis as 6th indicator
• [ ] Test with historical crisis periods
• [ ] Update SKILL.md with geopolitical indicator

Expected Impact:

• Early warning for market-wide risk events
• Better context for earnings-season volatility
• Complement to VIX (VIX is reactive, geopolitical is predictive)

Example Output:

⚠️ GEOPOLITICAL RISK: HIGH (72/100)
   Context: Elevated Taiwan tensions detected
   Market Impact: Risk-off sentiment likely

---

8. Sector-Specific Crisis Mapping

Status: ✅ DONE Priority: High Effort: 6-8 hours

Current Gap:

• No mapping between geopolitical events and affected sectors
• No automatic flagging of at-risk holdings

Proposed Risk Mapping:

| Geopolitical Event | Affected Sectors | Example Tickers | |-------------------|------------------|-----------------| | Taiwan conflict | Semiconductors | NVDA, AMD, TSM, INTC | | Russia-Ukraine | Energy, Agriculture | XLE, MOS, CF, NTR | | Middle East escalation | Oil, Defense | XOM, CVX, LMT, RTX | | China tensions | Tech supply chain, Retail | AAPL, QCOM, NKE, SBUX | | Banking crisis | Financials | JPM, BAC, WFC, C |

Tasks:

• [ ] Build event → sector → ticker mapping database
• [ ] Implement keyword detection in news feeds:
  • "Taiwan" + "military" → Semiconductors ⚠️
  • "Russia" + "sanctions" → Energy ⚠️
  • "Iran" + "attack" → Oil, Defense ⚠️
  • "China" + "tariffs" → Tech, Consumer ⚠️
• [ ] Add sector exposure check to analysis
• [ ] Generate automatic warnings in output
• [ ] Apply confidence penalty for high-risk sectors
• [ ] Test with historical crisis events
• [ ] Document in SKILL.md

Expected Impact:

• Automatic detection of sector-specific risks
• Clear warnings for exposed holdings
• Reduced false positives (only flag relevant sectors)

Example Output:

⚠️ SECTOR RISK ALERT: Semiconductors
   Event: Taiwan military exercises (elevated tensions)
   Impact: NVDA HIGH RISK - supply chain exposure
   Recommendation: HOLD → downgraded from BUY

---

9. Breaking News Check

Status: ✅ DONE Priority: Medium Effort: 4-6 hours

Current Gap:

• No real-time news scanning before analysis
• User might get stale recommendation during breaking events

Proposed Solution:

• Scan Google News or Reuters RSS before analysis
• Flag high-impact keywords within last 24 hours

Tasks:

• [ ] Choose news source (Google News RSS, Reuters API, or NewsAPI)
• [ ] Implement news fetching with 24-hour lookback
• [ ] Define crisis keywords:
  • War/Conflict: "war", "invasion", "military strike", "attack"
  • Economic: "recession", "crisis", "collapse", "default"
  • Regulatory: "sanctions", "embargo", "ban", "investigation"
  • Natural disaster: "earthquake", "hurricane", "pandemic"
• [ ] Add ticker-specific news check (company name + keywords)
• [ ] Generate automatic caveat in output
• [ ] Cache news check results (1 hour TTL)
• [ ] Add --skip-news flag for offline mode
• [ ] Test with historical crisis dates
• [ ] Document in SKILL.md

Expected Impact:

• Real-time awareness of breaking events
• Automatic caveats during high volatility
• User protection from stale recommendations

Example Output:

⚠️ BREAKING NEWS ALERT (last 6 hours):
   "Fed announces emergency rate hike"
   Impact: Market-wide volatility expected
   Caveat: Analysis may be outdated - rerun in 24h

---

10. Safe-Haven Indicators

Status: ✅ DONE Priority: Medium Effort: 3-4 hours

Current Gap:

• No detection of "risk-off" market regime
• VIX alone is insufficient (measures implied volatility, not capital flows)

Proposed Indicators:

• Gold (GLD) - Flight to safety
• US Treasuries (TLT) - Bond market fear
• USD Index (UUP) - Dollar strength during crisis

Risk-Off Detection Logic:

IF GLD +2% AND TLT +1% AND UUP +1% (all rising together)
THEN Market Regime = RISK-OFF

Tasks:

• [ ] Fetch GLD, TLT, UUP price data (5-day change)
• [ ] Implement risk-off detection algorithm
• [ ] Add to market context analysis
• [ ] Apply broad risk penalty:
  • Risk-off detected → Reduce all BUY confidence by 30%
  • Add caveat: "Market in risk-off mode - defensive positioning recommended"
• [ ] Test with historical crisis periods (2008, 2020, 2022)
• [ ] Add verbose output for safe-haven movements
• [ ] Document in SKILL.md

Expected Impact:

• Detect market-wide flight to safety
• Automatic risk reduction during panics
• Complement geopolitical risk scoring

Example Output:

🛡️ SAFE-HAVEN ALERT: Risk-off mode detected
   - Gold (GLD): +3.2% (5d)
   - Treasuries (TLT): +2.1% (5d)
   - USD Index: +1.8% (5d)
   Recommendation: Reduce equity exposure, favor defensives

---

General Improvements

11. Add Social Sentiment (Future Phase)

Status: Deferred Priority: Low Effort: 8-12 hours

Notes:

• Requires free API (Twitter/Reddit alternatives?)
• Most sentiment APIs are paid (StockTwits, etc.)
• Research needed for viable free sources

12. Add Fund Flows (Future Phase)

Status: Deferred Priority: Low Effort: 6-8 hours

Notes:

• Requires ETF flow data
• May need paid data source
• Research free alternatives

---

Implementation Priorities

v4.1.0 Complete

• ✅ Task #1 - Insider trading parsing via edgartools
• ✅ Task #3b - Market context caching (1h TTL)
• 🔧 Task #4 - SEC EDGAR rate limits (low priority, only if hitting limits)

Completed in v4.0.0

• ✅ Task #2 - Async parallel fetching (sentiment)
• ✅ Task #3 - Caching for shared indicators (sentiment + news)
• ✅ Task #7 - Geopolitical risk (keyword-based)
• ✅ Task #8 - Sector-specific crisis mapping
• ✅ Task #9 - Breaking news check
• ✅ Task #10 - Safe-haven indicators

---

Version History

• v5.0.0 (2026-01-16): Portfolio management, cryptocurrency support (Top 20), periodic analysis
• v4.1.0 (2026-01-16): Full insider trading parsing via edgartools, market context caching
• v4.0.0 (2026-01-15): Geopolitical risk, breaking news, safe-haven detection, sector crisis mapping
• v3.0.0 (2026-01-15): Sentiment analysis added with 5 indicators (3-4 typically working)
• v2.0.0: Market context, sector performance, earnings timing, momentum
• v1.0.0: Initial release with earnings, fundamentals, analysts, historical

Archive v6.1.0: 16 files, 74714 bytes

Files: App-Plan.md (14708b), docs/ARCHITECTURE.md (16594b), docs/CONCEPT.md (9101b), docs/HOT_SCANNER.md (5865b), docs/README.md (2405b), docs/USAGE.md (8898b), README.md (6390b), scripts/analyze_stock.py (89930b), scripts/dividends.py (13130b), scripts/hot_scanner.py (24620b), scripts/portfolio.py (18897b), scripts/test_stock_analysis.py (11958b), scripts/watchlist.py (11542b), SKILL.md (6963b), TODO.md (12848b), _meta.json (133b)

File v6.1.0:SKILL.md

---

name: stock-analysis description: Analyze stocks and cryptocurrencies using Yahoo Finance data. Supports portfolio management, watchlists with alerts, dividend analysis, 8-dimension stock scoring, and viral trend detection (Hot Scanner). Use for stock analysis, portfolio tracking, earnings reactions, crypto monitoring, or finding what's trending. version: 6.1.0 homepage: https://finance.yahoo.com commands:

• /stock - Analyze a stock or crypto (e.g., /stock AAPL)
• /stock_compare - Compare multiple tickers
• /stock_dividend - Analyze dividend metrics
• /stock_watch - Add/remove from watchlist
• /stock_alerts - Check triggered alerts
• /stock_hot - Find trending stocks & crypto (Hot Scanner)
• /portfolio - Show portfolio summary
• /portfolio_add - Add asset to portfolio metadata: {"clawdbot":{"emoji":"📈","requires":{"bins":["uv"],"env":[]},"install":[{"id":"uv-brew","kind":"brew","formula":"uv","bins":["uv"],"label":"Install uv (brew)"}]}}

---

Stock Analysis v6.1

Analyze US stocks and cryptocurrencies with 8-dimension analysis, portfolio management, watchlists, alerts, dividend analysis, and viral trend detection.

What's New in v6.1

• 🔥 Hot Scanner — Find viral stocks & crypto across multiple sources
• 🐦 Twitter/X Integration — Social sentiment via bird CLI
• 📰 Multi-Source Aggregation — CoinGecko, Google News, Yahoo Finance
• ⏰ Cron Support — Daily trend reports

What's in v6.0

• 🆕 Watchlist + Alerts — Price targets, stop losses, signal changes
• 🆕 Dividend Analysis — Yield, payout ratio, growth, safety score
• 🆕 Fast Mode — --fast skips slow analyses (insider, news)
• 🆕 Improved Performance — --no-insider for faster runs

Quick Commands

Stock Analysis

# Basic analysis
uv run {baseDir}/scripts/analyze_stock.py AAPL

# Fast mode (skips insider trading & breaking news)
uv run {baseDir}/scripts/analyze_stock.py AAPL --fast

# Compare multiple
uv run {baseDir}/scripts/analyze_stock.py AAPL MSFT GOOGL

# Crypto
uv run {baseDir}/scripts/analyze_stock.py BTC-USD ETH-USD

Dividend Analysis (NEW v6.0)

# Analyze dividends
uv run {baseDir}/scripts/dividends.py JNJ

# Compare dividend stocks
uv run {baseDir}/scripts/dividends.py JNJ PG KO MCD --output json

Dividend Metrics:

• Dividend Yield & Annual Payout
• Payout Ratio (safe/moderate/high/unsustainable)
• 5-Year Dividend Growth (CAGR)
• Consecutive Years of Increases
• Safety Score (0-100)
• Income Rating (excellent/good/moderate/poor)

Watchlist + Alerts (NEW v6.0)

# Add to watchlist
uv run {baseDir}/scripts/watchlist.py add AAPL

# With price target alert
uv run {baseDir}/scripts/watchlist.py add AAPL --target 200

# With stop loss alert
uv run {baseDir}/scripts/watchlist.py add AAPL --stop 150

# Alert on signal change (BUY→SELL)
uv run {baseDir}/scripts/watchlist.py add AAPL --alert-on signal

# View watchlist
uv run {baseDir}/scripts/watchlist.py list

# Check for triggered alerts
uv run {baseDir}/scripts/watchlist.py check
uv run {baseDir}/scripts/watchlist.py check --notify  # Telegram format

# Remove from watchlist
uv run {baseDir}/scripts/watchlist.py remove AAPL

Alert Types:

• 🎯 Target Hit — Price >= target
• 🛑 Stop Hit — Price <= stop
• 📊 Signal Change — BUY/HOLD/SELL changed

Portfolio Management

# Create portfolio
uv run {baseDir}/scripts/portfolio.py create "Tech Portfolio"

# Add assets
uv run {baseDir}/scripts/portfolio.py add AAPL --quantity 100 --cost 150
uv run {baseDir}/scripts/portfolio.py add BTC-USD --quantity 0.5 --cost 40000

# View portfolio
uv run {baseDir}/scripts/portfolio.py show

# Analyze with period returns
uv run {baseDir}/scripts/analyze_stock.py --portfolio "Tech Portfolio" --period weekly

🔥 Hot Scanner (NEW v6.1)

# Full scan - find what's trending NOW
python3 {baseDir}/scripts/hot_scanner.py

# Fast scan (skip social media)
python3 {baseDir}/scripts/hot_scanner.py --no-social

# JSON output for automation
python3 {baseDir}/scripts/hot_scanner.py --json

Data Sources:

• 📊 CoinGecko Trending — Top 15 trending coins
• 📈 CoinGecko Movers — Biggest gainers/losers
• 📰 Google News — Finance & crypto headlines
• 📉 Yahoo Finance — Gainers, losers, most active
• 🐦 Twitter/X — Social sentiment (requires auth)

Output:

• Top trending by mention count
• Crypto highlights with 24h changes
• Stock movers by category
• Breaking news with tickers

Twitter Setup (Optional):

1. Install bird: npm install -g @steipete/bird
2. Login to x.com in Safari/Chrome
3. Create .env with AUTH_TOKEN and CT0

Analysis Dimensions (8 for stocks, 3 for crypto)

Stocks

| Dimension | Weight | Description | |-----------|--------|-------------| | Earnings Surprise | 30% | EPS beat/miss | | Fundamentals | 20% | P/E, margins, growth | | Analyst Sentiment | 20% | Ratings, price targets | | Historical | 10% | Past earnings reactions | | Market Context | 10% | VIX, SPY/QQQ trends | | Sector | 15% | Relative strength | | Momentum | 15% | RSI, 52-week range | | Sentiment | 10% | Fear/Greed, shorts, insiders |

Crypto

• Market Cap & Category
• BTC Correlation (30-day)
• Momentum (RSI, range)

Sentiment Sub-Indicators

| Indicator | Source | Signal | |-----------|--------|--------| | Fear & Greed | CNN | Contrarian (fear=buy) | | Short Interest | Yahoo | Squeeze potential | | VIX Structure | Futures | Stress detection | | Insider Trades | SEC EDGAR | Smart money | | Put/Call Ratio | Options | Sentiment extreme |

Risk Detection

• ⚠️ Pre-Earnings — Warns if < 14 days to earnings
• ⚠️ Post-Spike — Flags if up >15% in 5 days
• ⚠️ Overbought — RSI >70 + near 52w high
• ⚠️ Risk-Off — GLD/TLT/UUP rising together
• ⚠️ Geopolitical — Taiwan, China, Russia, Middle East keywords
• ⚠️ Breaking News — Crisis keywords in last 24h

Performance Options

| Flag | Effect | Speed | |------|--------|-------| | (default) | Full analysis | 5-10s | | --no-insider | Skip SEC EDGAR | 3-5s | | --fast | Skip insider + news | 2-3s |

Supported Cryptos (Top 20)

BTC, ETH, BNB, SOL, XRP, ADA, DOGE, AVAX, DOT, MATIC, LINK, ATOM, UNI, LTC, BCH, XLM, ALGO, VET, FIL, NEAR

(Use -USD suffix: BTC-USD, ETH-USD)

Data Storage

| File | Location | |------|----------| | Portfolios | ~/.clawdbot/skills/stock-analysis/portfolios.json | | Watchlist | ~/.clawdbot/skills/stock-analysis/watchlist.json |

Limitations

• Yahoo Finance may lag 15-20 minutes
• Short interest lags ~2 weeks (FINRA)
• Insider trades lag 2-3 days (SEC filing)
• US markets only (non-US incomplete)
• Breaking news: 1h cache, keyword-based

Disclaimer

⚠️ NOT FINANCIAL ADVICE. For informational purposes only. Consult a licensed financial advisor before making investment decisions.

File v6.1.0:docs/README.md

Documentation

Stock Analysis v6.1

This folder contains detailed documentation for the Stock Analysis skill.

Contents

| Document | Description | |----------|-------------| | CONCEPT.md | Philosophy, ideas, and design rationale | | USAGE.md | Practical usage guide with examples | | ARCHITECTURE.md | Technical implementation details | | HOT_SCANNER.md | 🔥 Viral trend detection (NEW) |

Quick Links

For Users

Start with USAGE.md — it has practical examples for:

• Basic stock analysis
• Comparing stocks
• Crypto analysis
• Dividend investing
• Portfolio management
• Watchlist & alerts

For Understanding

Read CONCEPT.md to understand:

• Why 8 dimensions?
• How scoring works
• Contrarian signals
• Risk detection philosophy
• Limitations we acknowledge

For Developers

Check ARCHITECTURE.md for:

• System overview diagram
• Data flow
• Caching strategy
• File structure
• Performance optimization

Quick Start

# Analyze a stock
uv run scripts/analyze_stock.py AAPL

# Fast mode (2-3 seconds)
uv run scripts/analyze_stock.py AAPL --fast

# Dividend analysis
uv run scripts/dividends.py JNJ

# Watchlist
uv run scripts/watchlist.py add AAPL --target 200
uv run scripts/watchlist.py check

Key Concepts

The 8 Dimensions

1. Earnings Surprise (30%) — Did they beat expectations?
2. Fundamentals (20%) — P/E, margins, growth, debt
3. Analyst Sentiment (20%) — Professional consensus
4. Historical Patterns (10%) — Past earnings reactions
5. Market Context (10%) — VIX, SPY/QQQ trends
6. Sector Performance (15%) — Relative strength
7. Momentum (15%) — RSI, 52-week range
8. Sentiment (10%) — Fear/Greed, shorts, insiders

Signal Thresholds

| Score | Recommendation | |-------|----------------| | > +0.33 | BUY | | -0.33 to +0.33 | HOLD | | < -0.33 | SELL |

Risk Flags

• ⚠️ Pre-earnings (< 14 days)
• ⚠️ Post-spike (> 15% in 5 days)
• ⚠️ Overbought (RSI > 70 + near 52w high)
• ⚠️ Risk-off mode (GLD/TLT/UUP rising)
• ⚠️ Geopolitical keywords
• ⚠️ Breaking news alerts

Disclaimer

⚠️ NOT FINANCIAL ADVICE. For informational purposes only. Always do your own research and consult a licensed financial advisor.

File v6.1.0:README.md

📈 Stock Analysis v6.1

AI-powered stock & crypto analysis with portfolio management, watchlists, dividend analysis, and viral trend detection.

What's New in v6.1

• 🔥 Hot Scanner — Find viral stocks & crypto across multiple sources
• 🐦 Twitter/X Integration — Social sentiment via bird CLI
• 📰 Multi-Source Aggregation — CoinGecko, Google News, Yahoo Finance
• ⏰ Cron Support — Daily trend reports

What's New in v6.0

• 🆕 Watchlist + Alerts — Price targets, stop losses, signal change notifications
• 🆕 Dividend Analysis — Yield, payout ratio, growth rate, safety score
• 🆕 Fast Mode — Skip slow analyses for quick checks
• 🆕 Improved Commands — Better OpenClaw/Telegram integration
• 🆕 Test Suite — Unit tests for core functionality

Features

| Feature | Description | |---------|-------------| | 8-Dimension Analysis | Earnings, fundamentals, analysts, momentum, sentiment, sector, market, history | | Crypto Support | Top 20 cryptos with market cap, BTC correlation, momentum | | Portfolio Management | Track holdings, P&L, concentration warnings | | Watchlist + Alerts | Price targets, stop losses, signal changes | | Dividend Analysis | Yield, payout, growth, safety score | | Risk Detection | Geopolitical, earnings timing, overbought, risk-off | | Breaking News | Crisis keyword scanning (last 24h) |

Quick Start

Analyze Stocks

uv run scripts/analyze_stock.py AAPL
uv run scripts/analyze_stock.py AAPL MSFT GOOGL
uv run scripts/analyze_stock.py AAPL --fast  # Skip slow analyses

Analyze Crypto

uv run scripts/analyze_stock.py BTC-USD
uv run scripts/analyze_stock.py ETH-USD SOL-USD

Dividend Analysis

uv run scripts/dividends.py JNJ PG KO

Watchlist

uv run scripts/watchlist.py add AAPL --target 200 --stop 150
uv run scripts/watchlist.py list
uv run scripts/watchlist.py check --notify

Portfolio

uv run scripts/portfolio.py create "My Portfolio"
uv run scripts/portfolio.py add AAPL --quantity 100 --cost 150
uv run scripts/portfolio.py show

🔥 Hot Scanner (NEW)

# Full scan with all sources
python3 scripts/hot_scanner.py

# Fast scan (skip social media)
python3 scripts/hot_scanner.py --no-social

# JSON output for automation
python3 scripts/hot_scanner.py --json

Analysis Dimensions

Stocks (8 dimensions)

1. Earnings Surprise (30%) — EPS beat/miss
2. Fundamentals (20%) — P/E, margins, growth, debt
3. Analyst Sentiment (20%) — Ratings, price targets
4. Historical Patterns (10%) — Past earnings reactions
5. Market Context (10%) — VIX, SPY/QQQ trends
6. Sector Performance (15%) — Relative strength
7. Momentum (15%) — RSI, 52-week range
8. Sentiment (10%) — Fear/Greed, shorts, insiders

Crypto (3 dimensions)

• Market Cap & Category
• BTC Correlation (30-day)
• Momentum (RSI, range)

Dividend Metrics

| Metric | Description | |--------|-------------| | Yield | Annual dividend / price | | Payout Ratio | Dividend / EPS | | 5Y Growth | CAGR of dividend | | Consecutive Years | Years of increases | | Safety Score | 0-100 composite | | Income Rating | Excellent → Poor |

🔥 Hot Scanner

Find what's trending RIGHT NOW across stocks & crypto.

Data Sources

| Source | What it finds | |--------|---------------| | CoinGecko Trending | Top 15 trending coins | | CoinGecko Movers | Biggest gainers/losers (>3%) | | Google News | Breaking finance & crypto news | | Yahoo Finance | Top gainers, losers, most active | | Twitter/X | Social sentiment (requires auth) |

Output

📊 TOP TRENDING (by buzz):
   1. BTC      (6 pts) [CoinGecko, Google News] 📉 bearish (-2.5%)
   2. ETH      (5 pts) [CoinGecko, Twitter] 📉 bearish (-7.2%)
   3. NVDA     (3 pts) [Google News, Yahoo] 📰 Earnings beat...

🪙 CRYPTO HIGHLIGHTS:
   🚀 RIVER    River              +14.0%
   📉 BTC      Bitcoin             -2.5%

📈 STOCK MOVERS:
   🟢 NVDA (gainers)
   🔴 TSLA (losers)

📰 BREAKING NEWS:
   [BTC, ETH] Crypto crash: $2.5B liquidated...

Twitter/X Setup (Optional)

1. Install bird CLI: npm install -g @steipete/bird
2. Login to x.com in Safari/Chrome
3. Create .env file:

AUTH_TOKEN=your_auth_token
CT0=your_ct0_token

Get tokens from browser DevTools → Application → Cookies → x.com

Automation

Set up a daily cron job for morning reports:

# Run at 8 AM daily
0 8 * * * python3 /path/to/hot_scanner.py --no-social >> /var/log/hot_scanner.log

Risk Detection

• ⚠️ Pre-earnings warning (< 14 days)
• ⚠️ Post-earnings spike (> 15% in 5 days)
• ⚠️ Overbought (RSI > 70 + near 52w high)
• ⚠️ Risk-off mode (GLD/TLT/UUP rising)
• ⚠️ Geopolitical keywords (Taiwan, China, etc.)
• ⚠️ Breaking news alerts

Performance Options

| Flag | Speed | Description | |------|-------|-------------| | (default) | 5-10s | Full analysis | | --no-insider | 3-5s | Skip SEC EDGAR | | --fast | 2-3s | Skip insider + news |

Data Sources

• Yahoo Finance — Prices, fundamentals, movers
• CoinGecko — Crypto trending, market data
• CNN Fear & Greed — Sentiment
• SEC EDGAR — Insider trading
• Google News RSS — Breaking news
• Twitter/X — Social sentiment (via bird CLI)

Storage

| Data | Location | |------|----------| | Portfolios | ~/.clawdbot/skills/stock-analysis/portfolios.json | | Watchlist | ~/.clawdbot/skills/stock-analysis/watchlist.json |

Testing

uv run pytest scripts/test_stock_analysis.py -v

Limitations

• Yahoo Finance may lag 15-20 minutes
• Short interest lags ~2 weeks (FINRA)
• US markets only

Disclaimer

⚠️ NOT FINANCIAL ADVICE. For informational purposes only. Consult a licensed financial advisor before making investment decisions.

---

Built for OpenClaw 🦞 | ClawHub

File v6.1.0:_meta.json

{ "ownerId": "kn77fv9851hjcqe52zqx0bhhbx7z680h", "slug": "stock-analysis", "version": "6.1.0", "publishedAt": 1770030459843 }

File v6.1.0:App-Plan.md

StockPulse - Commercial Product Roadmap

Vision

Transform the stock-analysis skill into StockPulse, a commercial mobile app for retail investors with AI-powered stock and crypto analysis, portfolio tracking, and personalized alerts.

Technical Decisions

• Mobile: Flutter (iOS + Android cross-platform)
• Backend: Python FastAPI on AWS (ECS/Lambda)
• Database: PostgreSQL (RDS) + Redis (ElastiCache)
• Auth: AWS Cognito or Firebase Auth
• Monetization: Freemium + Subscription ($9.99/mo or $79.99/yr)

---

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                      MOBILE APP (Flutter)                        │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐           │
│  │Dashboard │ │Portfolio │ │ Analysis │ │ Alerts   │           │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘           │
└─────────────────────────────────────────────────────────────────┘
                              │ HTTPS/REST
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      API GATEWAY (AWS)                           │
│                   Rate Limiting, Auth, Caching                   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   BACKEND (FastAPI on ECS)                       │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │
│  │ Auth Service │ │ Analysis API │ │ Portfolio API│            │
│  └──────────────┘ └──────────────┘ └──────────────┘            │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │
│  │ Alerts Svc   │ │ Subscription │ │ User Service │            │
│  └──────────────┘ └──────────────┘ └──────────────┘            │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  PostgreSQL  │     │    Redis     │     │     S3       │
│   (RDS)      │     │ (ElastiCache)│     │  (Reports)   │
└──────────────┘     └──────────────┘     └──────────────┘

                    BACKGROUND WORKERS (Lambda/ECS)
┌─────────────────────────────────────────────────────────────────┐
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │
│  │Price Updater │ │Alert Checker │ │Daily Reports │            │
│  │  (5 min)     │ │  (1 min)     │ │  (Daily)     │            │
│  └──────────────┘ └──────────────┘ └──────────────┘            │
└─────────────────────────────────────────────────────────────────┘

---

Feature Tiers

Free Tier

• 1 portfolio (max 10 assets)
• Basic stock/crypto analysis
• Daily market summary
• Limited to 5 analyses/day
• Ads displayed

Premium ($9.99/mo)

• Unlimited portfolios & assets
• Full 8-dimension analysis
• Real-time price alerts
• Push notifications
• Period reports (daily/weekly/monthly)
• No ads
• Priority support

Pro ($19.99/mo) - Future

• API access
• Custom watchlists
• Advanced screeners
• Export to CSV/PDF
• Portfolio optimization suggestions

---

Development Phases

Phase 1: Backend API

Goal: Convert Python scripts to production REST API

Tasks:

1. Project Setup

   • FastAPI project structure
   • Docker containerization
   • CI/CD pipeline (GitHub Actions)
   • AWS infrastructure (Terraform)

2. Core API Endpoints

   POST /auth/register
   POST /auth/login
   POST /auth/refresh
   
   GET  /analysis/{ticker}
   POST /analysis/batch
   
   GET  /portfolios
   POST /portfolios
   PUT  /portfolios/{id}
   DELETE /portfolios/{id}
   
   GET  /portfolios/{id}/assets
   POST /portfolios/{id}/assets
   PUT  /portfolios/{id}/assets/{ticker}
   DELETE /portfolios/{id}/assets/{ticker}
   
   GET  /portfolios/{id}/performance?period=weekly
   GET  /portfolios/{id}/summary
   
   GET  /alerts
   POST /alerts
   DELETE /alerts/{id}
   
   GET  /user/subscription
   POST /user/subscription/upgrade
   

3. Database Schema

   users (id, email, password_hash, created_at, subscription_tier)
   portfolios (id, user_id, name, created_at, updated_at)
   assets (id, portfolio_id, ticker, asset_type, quantity, cost_basis)
   alerts (id, user_id, ticker, condition, threshold, enabled)
   analysis_cache (ticker, data, expires_at)
   subscriptions (id, user_id, stripe_id, status, expires_at)
   

4. Refactor Existing Code

   • Extract analyze_stock.py into modules:
     • analysis/earnings.py
     • analysis/fundamentals.py
     • analysis/sentiment.py
     • analysis/crypto.py
     • analysis/market_context.py
   • Add async support throughout
   • Implement proper caching (Redis)
   • Rate limiting per user tier

Files to Create:

backend/
├── app/
│   ├── main.py              # FastAPI app
│   ├── config.py            # Settings
│   ├── models/              # SQLAlchemy models
│   ├── schemas/             # Pydantic schemas
│   ├── routers/             # API routes
│   │   ├── auth.py
│   │   ├── analysis.py
│   │   ├── portfolios.py
│   │   └── alerts.py
│   ├── services/            # Business logic
│   │   ├── analysis/        # Refactored from analyze_stock.py
│   │   ├── portfolio.py
│   │   └── alerts.py
│   └── workers/             # Background tasks
├── tests/
├── Dockerfile
├── docker-compose.yml
└── requirements.txt

---

Phase 2: Flutter Mobile App

Goal: Build polished cross-platform mobile app

Screens:

1. Onboarding - Welcome, feature highlights, sign up/login
2. Dashboard - Market overview, portfolio summary, alerts
3. Analysis - Search ticker, view full analysis, save to portfolio
4. Portfolio - List portfolios, asset breakdown, P&L chart
5. Alerts - Manage price alerts, notification settings
6. Settings - Account, subscription, preferences

Key Flutter Packages:

dependencies:
  flutter_bloc: ^8.0.0      # State management
  dio: ^5.0.0               # HTTP client
  go_router: ^12.0.0        # Navigation
  fl_chart: ^0.65.0         # Charts
  firebase_messaging: ^14.0.0  # Push notifications
  in_app_purchase: ^3.0.0   # Subscriptions
  shared_preferences: ^2.0.0
  flutter_secure_storage: ^9.0.0

App Structure:

lib/
├── main.dart
├── app/
│   ├── routes.dart
│   └── theme.dart
├── features/
│   ├── auth/
│   │   ├── bloc/
│   │   ├── screens/
│   │   └── widgets/
│   ├── dashboard/
│   ├── analysis/
│   ├── portfolio/
│   ├── alerts/
│   └── settings/
├── core/
│   ├── api/
│   ├── models/
│   └── utils/
└── shared/
    └── widgets/

---

Phase 3: Infrastructure & DevOps

Goal: Production-ready cloud infrastructure

AWS Services:

• ECS Fargate - Backend containers
• RDS PostgreSQL - Database
• ElastiCache Redis - Caching
• S3 - Static assets, reports
• CloudFront - CDN
• Cognito - Authentication
• SES - Email notifications
• SNS - Push notifications
• CloudWatch - Monitoring
• WAF - Security

Terraform Modules:

infrastructure/
├── main.tf
├── variables.tf
├── modules/
│   ├── vpc/
│   ├── ecs/
│   ├── rds/
│   ├── elasticache/
│   └── cognito/
└── environments/
    ├── dev/
    ├── staging/
    └── prod/

Estimated Monthly Costs (Production):

| Service | Est. Cost | |---------|-----------| | ECS Fargate (2 tasks) | $50-100 | | RDS (db.t3.small) | $30-50 | | ElastiCache (cache.t3.micro) | $15-25 | | S3 + CloudFront | $10-20 | | Other (Cognito, SES, etc.) | $20-30 | | Total | $125-225/mo |

---

Phase 4: Payments & Subscriptions

Goal: Integrate Stripe for subscriptions

Implementation:

1. Stripe subscription products (Free, Premium, Pro)
2. In-app purchase for iOS/Android
3. Webhook handlers for subscription events
4. Grace period handling
5. Receipt validation

Stripe Integration:

# Backend webhook handler
@router.post("/webhooks/stripe")
async def stripe_webhook(request: Request):
    event = stripe.Webhook.construct_event(...)

    if event.type == "customer.subscription.updated":
        update_user_tier(event.data.object)
    elif event.type == "customer.subscription.deleted":
        downgrade_to_free(event.data.object)

---

Phase 5: Push Notifications & Alerts

Goal: Real-time price alerts and notifications

Alert Types:

• Price above/below threshold
• Percentage change (daily)
• Earnings announcement
• Breaking news (geopolitical)
• Portfolio performance

Implementation:

• Firebase Cloud Messaging (FCM)
• Background worker checks alerts every minute
• Rate limit: max 10 alerts/day per free user

---

Phase 6: Analytics & Monitoring

Goal: Track usage, errors, business metrics

Tools:

• Mixpanel/Amplitude - Product analytics
• Sentry - Error tracking
• CloudWatch - Infrastructure metrics
• Custom dashboard - Business KPIs

Key Metrics:

• DAU/MAU
• Conversion rate (free → premium)
• Churn rate
• API response times
• Analysis accuracy feedback

---

Security Considerations

1. Authentication

   • JWT tokens with refresh rotation
   • OAuth2 (Google, Apple Sign-In)
   • 2FA optional for premium users

2. Data Protection

   • Encrypt PII at rest (RDS encryption)
   • TLS 1.3 for all API traffic
   • No plaintext passwords

3. API Security

   • Rate limiting per tier
   • Input validation (Pydantic)
   • SQL injection prevention (SQLAlchemy ORM)
   • CORS configuration

4. Compliance

   • Privacy policy
   • Terms of service
   • GDPR data export/deletion
   • Financial disclaimer (not investment advice)

---

Risks & Mitigations

| Risk | Impact | Mitigation | |------|--------|------------| | Yahoo Finance rate limits | High | Implement caching, use paid API fallback | | App store rejection | Medium | Follow guidelines, proper disclaimers | | Data accuracy issues | High | Clear disclaimers, data validation | | Security breach | Critical | Security audit, penetration testing | | Low conversion rate | Medium | A/B testing, feature gating |

---

Success Metrics (Year 1)

| Metric | Target | |--------|--------| | App downloads | 10,000+ | | DAU | 1,000+ | | Premium subscribers | 500+ | | Monthly revenue | $5,000+ | | App store rating | 4.5+ stars | | Churn rate | <5%/month |

---

Next Steps (Immediate)

1. Validate idea - User interviews, landing page
2. Design - Figma mockups for key screens
3. Backend MVP - Core API endpoints
4. Flutter prototype - Basic app with analysis feature
5. Beta testing - TestFlight/Google Play beta

---

Repository Structure (Final)

stockpulse/
├── backend/                 # FastAPI backend
│   ├── app/
│   ├── tests/
│   ├── Dockerfile
│   └── requirements.txt
├── mobile/                  # Flutter app
│   ├── lib/
│   ├── test/
│   ├── ios/
│   ├── android/
│   └── pubspec.yaml
├── infrastructure/          # Terraform
│   ├── modules/
│   └── environments/
├── docs/                    # Documentation
│   ├── api/
│   └── architecture/
└── scripts/                 # Utility scripts

---

Timeline Summary (Planning Only)

| Phase | Duration | Dependencies | |-------|----------|--------------| | 1. Backend API | 4-6 weeks | - | | 2. Flutter App | 6-8 weeks | Phase 1 | | 3. Infrastructure | 2-3 weeks | Phase 1 | | 4. Payments | 2 weeks | Phase 2, 3 | | 5. Notifications | 2 weeks | Phase 2, 3 | | 6. Analytics | 1 week | Phase 2 | | Total | 17-22 weeks | |

This is a planning document. No fixed timeline - execute phases as resources allow.

---

Disclaimer: This tool is for informational purposes only and does NOT constitute financial advice.

File v6.1.0:docs/ARCHITECTURE.md

Technical Architecture

How Stock Analysis v6.0 works under the hood.

System Overview

┌─────────────────────────────────────────────────────────────────────┐
│                        Stock Analysis v6.0                           │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │                    CLI Interface                              │   │
│  │  analyze_stock.py | dividends.py | watchlist.py | portfolio.py│   │
│  └────────────────────────────┬─────────────────────────────────┘   │
│                               │                                      │
│  ┌────────────────────────────▼─────────────────────────────────┐   │
│  │                   Analysis Engine                             │   │
│  │                                                               │   │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐            │   │
│  │  │Earnings │ │Fundmtls │ │Analysts │ │Historical│            │   │
│  │  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘            │   │
│  │       │           │           │           │                   │   │
│  │  ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐            │   │
│  │  │ Market  │ │ Sector  │ │Momentum │ │Sentiment│            │   │
│  │  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘            │   │
│  │       │           │           │           │                   │   │
│  │       └───────────┴───────────┴───────────┘                   │   │
│  │                          │                                    │   │
│  │                    [Synthesizer]                              │   │
│  │                          │                                    │   │
│  │                    [Signal Output]                            │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                               │                                      │
│  ┌────────────────────────────▼─────────────────────────────────┐   │
│  │                    Data Sources                               │   │
│  │                                                               │   │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐            │   │
│  │  │ Yahoo   │ │  CNN    │ │   SEC   │ │ Google  │            │   │
│  │  │ Finance │ │Fear/Grd │ │ EDGAR   │ │  News   │            │   │
│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘            │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

---

Core Components

1. Data Fetching (fetch_stock_data)

def fetch_stock_data(ticker: str, verbose: bool = False) -> StockData | None:
    """Fetch stock data from Yahoo Finance with retry logic."""

Features:

• 3 retries with exponential backoff
• Graceful handling of missing data
• Asset type detection (stock vs crypto)

Returns: StockData dataclass with:

• info: Company fundamentals
• earnings_history: Past earnings
• analyst_info: Ratings and targets
• price_history: 1-year OHLCV

2. Analysis Modules

Each dimension has its own analyzer:

| Module | Function | Returns | |--------|----------|---------| | Earnings | analyze_earnings_surprise() | EarningsSurprise | | Fundamentals | analyze_fundamentals() | Fundamentals | | Analysts | analyze_analyst_sentiment() | AnalystSentiment | | Historical | analyze_historical_patterns() | HistoricalPatterns | | Market | analyze_market_context() | MarketContext | | Sector | analyze_sector_performance() | SectorComparison | | Momentum | analyze_momentum() | MomentumAnalysis | | Sentiment | analyze_sentiment() | SentimentAnalysis |

3. Sentiment Sub-Analyzers

Sentiment runs 5 parallel async tasks:

results = await asyncio.gather(
    get_fear_greed_index(),      # CNN Fear & Greed
    get_short_interest(data),    # Yahoo Finance
    get_vix_term_structure(),    # VIX Futures
    get_insider_activity(),      # SEC EDGAR
    get_put_call_ratio(data),    # Options Chain
    return_exceptions=True
)

Timeout: 10 seconds per indicator Minimum: 2 of 5 indicators required

4. Signal Synthesis

def synthesize_signal(
    ticker, company_name,
    earnings, fundamentals, analysts, historical,
    market_context, sector, earnings_timing,
    momentum, sentiment,
    breaking_news, geopolitical_risk_warning, geopolitical_risk_penalty
) -> Signal:

Scoring:

1. Collect available component scores
2. Apply normalized weights
3. Calculate weighted average → final_score
4. Apply adjustments (timing, overbought, risk-off)
5. Determine recommendation threshold

Thresholds:

if final_score > 0.33:
    recommendation = "BUY"
elif final_score < -0.33:
    recommendation = "SELL"
else:
    recommendation = "HOLD"

---

Caching Strategy

What's Cached

| Data | TTL | Key | |------|-----|-----| | Market Context | 1 hour | market_context | | Fear & Greed | 1 hour | fear_greed | | VIX Structure | 1 hour | vix_structure | | Breaking News | 1 hour | breaking_news |

Cache Implementation

_SENTIMENT_CACHE = {}
_CACHE_TTL_SECONDS = 3600  # 1 hour

def _get_cached(key: str):
    if key in _SENTIMENT_CACHE:
        value, timestamp = _SENTIMENT_CACHE[key]
        if time.time() - timestamp < _CACHE_TTL_SECONDS:
            return value
    return None

def _set_cache(key: str, value):
    _SENTIMENT_CACHE[key] = (value, time.time())

Why This Matters

• First stock: ~8 seconds (full fetch)
• Second stock: ~4 seconds (reuses market data)
• Same stock again: ~4 seconds (no stock-level cache)

---

Data Flow

Single Stock Analysis

User Input: "AAPL"
     │
     ▼
┌─────────────────────────────────────────────────────────────┐
│ 1. FETCH DATA (yfinance)                                    │
│    - Stock info, earnings, price history                    │
│    - ~2 seconds                                             │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. PARALLEL ANALYSIS                                        │
│                                                             │
│    ┌──────────┐ ┌──────────┐ ┌──────────┐                  │
│    │ Earnings │ │Fundmtls  │ │ Analysts │  ... (sync)      │
│    └──────────┘ └──────────┘ └──────────┘                  │
│                                                             │
│    ┌────────────────────────────────────┐                  │
│    │ Market Context (cached or fetch)   │  ~1 second       │
│    └────────────────────────────────────┘                  │
│                                                             │
│    ┌────────────────────────────────────┐                  │
│    │ Sentiment (5 async tasks)          │  ~3-5 seconds    │
│    │  - Fear/Greed (cached)             │                  │
│    │  - Short Interest                  │                  │
│    │  - VIX Structure (cached)          │                  │
│    │  - Insider Trading (slow!)         │                  │
│    │  - Put/Call Ratio                  │                  │
│    └────────────────────────────────────┘                  │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. SYNTHESIZE SIGNAL                                        │
│    - Combine scores with weights                            │
│    - Apply adjustments                                      │
│    - Generate caveats                                       │
│    - ~10 ms                                                 │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. OUTPUT                                                   │
│    - Text or JSON format                                    │
│    - Include disclaimer                                     │
└─────────────────────────────────────────────────────────────┘

---

Risk Detection

Geopolitical Risk

GEOPOLITICAL_RISK_MAP = {
    "taiwan": {
        "keywords": ["taiwan", "tsmc", "strait"],
        "sectors": ["Technology", "Communication Services"],
        "affected_tickers": ["NVDA", "AMD", "TSM", ...],
        "impact": "Semiconductor supply chain disruption",
    },
    # ... china, russia_ukraine, middle_east, banking_crisis
}

Process:

1. Check breaking news for keywords
2. If keyword found, check if ticker in affected list
3. Apply confidence penalty (30% direct, 15% sector)

Breaking News

def check_breaking_news(verbose: bool = False) -> list[str] | None:
    """Scan Google News RSS for crisis keywords (last 24h)."""

Crisis Keywords:

CRISIS_KEYWORDS = {
    "war": ["war", "invasion", "military strike", ...],
    "economic": ["recession", "crisis", "collapse", ...],
    "regulatory": ["sanctions", "embargo", "ban", ...],
    "disaster": ["earthquake", "hurricane", "pandemic", ...],
    "financial": ["emergency rate", "bailout", ...],
}

---

File Structure

stock-analysis/
├── scripts/
│   ├── analyze_stock.py      # Main analysis engine (2500+ lines)
│   ├── portfolio.py          # Portfolio management
│   ├── dividends.py          # Dividend analysis
│   ├── watchlist.py          # Watchlist + alerts
│   └── test_stock_analysis.py # Unit tests
├── docs/
│   ├── CONCEPT.md            # Philosophy & ideas
│   ├── USAGE.md              # Practical guide
│   └── ARCHITECTURE.md       # This file
├── SKILL.md                  # OpenClaw skill definition
├── README.md                 # Project overview
└── .clawdhub/                # ClawHub metadata

---

Data Storage

Portfolio (portfolios.json)

{
  "portfolios": [
    {
      "name": "Retirement",
      "created_at": "2024-01-01T00:00:00Z",
      "assets": [
        {
          "ticker": "AAPL",
          "quantity": 100,
          "cost_basis": 150.00,
          "type": "stock",
          "added_at": "2024-01-01T00:00:00Z"
        }
      ]
    }
  ]
}

Watchlist (watchlist.json)

[
  {
    "ticker": "NVDA",
    "added_at": "2024-01-15T10:30:00Z",
    "price_at_add": 700.00,
    "target_price": 800.00,
    "stop_price": 600.00,
    "alert_on_signal": true,
    "last_signal": "BUY",
    "last_check": "2024-01-20T08:00:00Z"
  }
]

---

Dependencies

# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "yfinance>=0.2.40",      # Stock data
#     "pandas>=2.0.0",         # Data manipulation
#     "fear-and-greed>=0.4",   # CNN Fear & Greed
#     "edgartools>=2.0.0",     # SEC EDGAR filings
#     "feedparser>=6.0.0",     # RSS parsing
# ]
# ///

Why These:

• yfinance: Most reliable free stock API
• pandas: Industry standard for financial data
• fear-and-greed: Simple CNN F&G wrapper
• edgartools: Clean SEC EDGAR access
• feedparser: Robust RSS parsing

---

Performance Optimization

Current

| Operation | Time | |-----------|------| | yfinance fetch | ~2s | | Market context | ~1s (cached after) | | Insider trading | ~3-5s (slowest!) | | Sentiment (parallel) | ~3-5s | | Synthesis | ~10ms | | Total | 5-10s |

Fast Mode (--fast)

Skips:

• Insider trading (SEC EDGAR)
• Breaking news scan

Result: 2-3 seconds

Future Optimizations

1. Stock-level caching — Cache fundamentals for 24h
2. Batch API calls — yfinance supports multiple tickers
3. Background refresh — Pre-fetch watchlist data
4. Local SEC data — Avoid EDGAR API calls

---

Error Handling

Retry Strategy

max_retries = 3
for attempt in range(max_retries):
    try:
        # fetch data
    except Exception as e:
        wait_time = 2 ** attempt  # Exponential backoff: 1, 2, 4 seconds
        time.sleep(wait_time)

Graceful Degradation

• Missing earnings → Skip dimension, reweight
• Missing analysts → Skip dimension, reweight
• Missing sentiment → Skip dimension, reweight
• API failure → Return None, continue with partial data

Minimum Requirements

• At least 2 of 8 dimensions required
• At least 2 of 5 sentiment indicators required
• Otherwise → HOLD with low confidence

File v6.1.0:docs/CONCEPT.md

Concept & Philosophy

The Problem

Making investment decisions is hard. There's too much data, too many opinions, and too much noise. Most retail investors either:

1. Over-simplify — Buy based on headlines or tips
2. Over-complicate — Get lost in endless research
3. Freeze — Analysis paralysis, never act

The Solution

Stock Analysis provides a structured, multi-dimensional framework that:

• Aggregates data from multiple sources
• Weighs different factors objectively
• Produces a clear BUY / HOLD / SELL signal
• Explains the reasoning with bullet points
• Flags risks and caveats

Think of it as a second opinion — not a replacement for your judgment, but a systematic check.

---

Core Philosophy

1. Multiple Perspectives Beat Single Metrics

No single metric tells the whole story:

• A low P/E might mean "cheap" or "dying business"
• High analyst ratings might mean "priced in" or "genuine upside"
• Strong momentum might mean "trend" or "overbought"

By combining 8 dimensions, we get a more complete picture.

2. Contrarian Signals Matter

Some of our best signals are contrarian:

| Indicator | Crowd Says | We Interpret | |-----------|------------|--------------| | Extreme Fear (Fear & Greed < 25) | "Sell everything!" | Potential buy opportunity | | Extreme Greed (> 75) | "Easy money!" | Caution, reduce exposure | | High Short Interest + Days to Cover | "Stock is doomed" | Squeeze potential | | Insider Buying | (often ignored) | Smart money signal |

3. Timing Matters

A good stock at the wrong time is a bad trade:

• Pre-earnings — Even strong stocks can gap down 10%+
• Post-spike — Buying after a 20% run often means buying the top
• Overbought — RSI > 70 + near 52-week high = high-risk entry

We detect these timing issues and adjust recommendations accordingly.

4. Context Changes Everything

The same stock behaves differently in different market regimes:

| Regime | Characteristics | Impact | |--------|-----------------|--------| | Bull | VIX < 20, SPY up | BUY signals more reliable | | Bear | VIX > 30, SPY down | Even good stocks fall | | Risk-Off | GLD/TLT/UUP rising | Flight to safety, reduce equity | | Geopolitical | Crisis keywords | Sector-specific penalties |

5. Dividends Are Different

Income investors have different priorities than growth investors:

| Growth Investor | Income Investor | |-----------------|-----------------| | Price appreciation | Dividend yield | | Revenue growth | Payout sustainability | | Market share | Dividend growth rate | | P/E ratio | Safety of payment |

That's why we have a separate dividend analysis module.

---

The 8 Dimensions

Why These 8?

Each dimension captures a different aspect of investment quality:

┌─────────────────────────────────────────────────────────────┐
│                    FUNDAMENTAL VALUE                         │
│  ┌─────────────────┐  ┌─────────────────┐                   │
│  │    Earnings     │  │  Fundamentals   │                   │
│  │    Surprise     │  │   (P/E, etc.)   │                   │
│  │     (30%)       │  │     (20%)       │                   │
│  └─────────────────┘  └─────────────────┘                   │
├─────────────────────────────────────────────────────────────┤
│                    EXTERNAL VALIDATION                       │
│  ┌─────────────────┐  ┌─────────────────┐                   │
│  │    Analyst      │  │   Historical    │                   │
│  │   Sentiment     │  │    Patterns     │                   │
│  │     (20%)       │  │     (10%)       │                   │
│  └─────────────────┘  └─────────────────┘                   │
├─────────────────────────────────────────────────────────────┤
│                    MARKET ENVIRONMENT                        │
│  ┌─────────────────┐  ┌─────────────────┐                   │
│  │    Market       │  │     Sector      │                   │
│  │    Context      │  │  Performance    │                   │
│  │     (10%)       │  │     (15%)       │                   │
│  └─────────────────┘  └─────────────────┘                   │
├─────────────────────────────────────────────────────────────┤
│                    TECHNICAL & SENTIMENT                     │
│  ┌─────────────────┐  ┌─────────────────┐                   │
│  │    Momentum     │  │   Sentiment     │                   │
│  │  (RSI, range)   │  │ (Fear, shorts)  │                   │
│  │     (15%)       │  │     (10%)       │                   │
│  └─────────────────┘  └─────────────────┘                   │
└─────────────────────────────────────────────────────────────┘

Weight Rationale

| Weight | Dimension | Rationale | |--------|-----------|-----------| | 30% | Earnings | Most direct measure of company performance | | 20% | Fundamentals | Long-term value indicators | | 20% | Analysts | Professional consensus (with skepticism) | | 15% | Sector | Relative performance matters | | 15% | Momentum | Trend is your friend (until it isn't) | | 10% | Market | Rising tide lifts all boats | | 10% | Sentiment | Contrarian edge | | 10% | Historical | Past behavior predicts future reactions |

Note: Weights auto-normalize when data is missing.

---

Risk Detection Philosophy

"Don't Lose Money"

Warren Buffett's Rule #1. Our risk detection is designed to prevent bad entries:

1. Pre-Earnings Hold — Don't buy right before a binary event
2. Post-Spike Caution — Don't chase a run-up
3. Overbought Warning — Technical exhaustion
4. Risk-Off Mode — When even good stocks fall
5. Geopolitical Flags — Sector-specific event risk

False Positive vs False Negative

We err on the side of caution:

• Missing a 10% gain is annoying
• Catching a 30% loss is devastating

That's why our caveats are prominent, and we downgrade BUY → HOLD liberally.

---

Crypto Adaptation

Crypto is fundamentally different from stocks:

| Stocks | Crypto | |--------|--------| | Earnings | No earnings | | P/E Ratio | Market cap tiers | | Sector ETFs | BTC correlation | | Dividends | Staking yields (not tracked) | | SEC Filings | No filings |

We adapted the framework:

• 3 dimensions instead of 8
• BTC correlation as a key metric
• Category classification (L1, DeFi, etc.)
• No sentiment (no insider data for crypto)

---

Why Not Just Use [X]?

vs. Stock Screeners (Finviz, etc.)

• Screeners show data, we provide recommendations
• We combine fundamental + technical + sentiment
• We flag timing and risk issues

vs. Analyst Reports

• Analysts have conflicts of interest
• Reports are often stale
• We aggregate multiple signals

vs. Trading Bots

• Bots execute, we advise
• We explain reasoning
• Human stays in control

vs. ChatGPT/AI Chat

• We have structured scoring, not just conversation
• Real-time data fetching
• Consistent methodology

---

Limitations We Acknowledge

1. Data Lag — Yahoo Finance is 15-20 min delayed
2. US Focus — International stocks have incomplete data
3. No Execution — We advise, you decide and execute
4. Past ≠ Future — All models have limits
5. Black Swans — Can't predict unpredictable events

This is a tool, not a crystal ball.

---

The Bottom Line

Stock Analysis v6.0 is designed to be your systematic second opinion:

• ✅ Multi-dimensional analysis
• ✅ Clear recommendations
• ✅ Risk detection
• ✅ Explained reasoning
• ✅ Fast and automated

NOT:

• ❌ Financial advice
• ❌ Guaranteed returns
• ❌ Replacement for research
• ❌ Trading signals

Use it wisely. 📈

File v6.1.0:docs/HOT_SCANNER.md

🔥 Hot Scanner

Find viral stocks & crypto trends in real-time by aggregating multiple data sources.

Overview

The Hot Scanner answers one question: "What's hot right now?"

It aggregates data from:

• CoinGecko (trending coins, biggest movers)
• Google News (finance & crypto headlines)
• Yahoo Finance (gainers, losers, most active)
• Twitter/X (social sentiment, optional)

Quick Start

# Full scan with all sources
python3 scripts/hot_scanner.py

# Skip social media (faster)
python3 scripts/hot_scanner.py --no-social

# JSON output for automation
python3 scripts/hot_scanner.py --json

Output Format

Console Output

============================================================
🔥 HOT SCANNER v2 - What's Trending Right Now?
📅 2026-02-02 10:45:30 UTC
============================================================

📊 TOP TRENDING (by buzz):
   1. BTC      (6 pts) [CoinGecko, Google News] 📉 bearish (-2.5%)
   2. ETH      (5 pts) [CoinGecko, Twitter] 📉 bearish (-7.2%)
   3. NVDA     (3 pts) [Google News, Yahoo] 📰 Earnings beat...

🪙 CRYPTO HIGHLIGHTS:
   🚀 RIVER    River              +14.0%
   📉 BTC      Bitcoin             -2.5%
   📉 ETH      Ethereum            -7.2%

📈 STOCK MOVERS:
   🟢 NVDA (gainers)
   🔴 TSLA (losers)
   📊 AAPL (most active)

🐦 SOCIAL BUZZ:
   [twitter] Bitcoin to $100k prediction...
   [reddit_wsb] GME yolo update...

📰 BREAKING NEWS:
   [BTC, ETH] Crypto crash: $2.5B liquidated...
   [NVDA] Nvidia beats earnings expectations...

JSON Output

{
  "scan_time": "2026-02-02T10:45:30+00:00",
  "top_trending": [
    {
      "symbol": "BTC",
      "mentions": 6,
      "sources": ["CoinGecko Trending", "Google News"],
      "signals": ["📉 bearish (-2.5%)"]
    }
  ],
  "crypto_highlights": [...],
  "stock_highlights": [...],
  "social_buzz": [...],
  "breaking_news": [...]
}

Data Sources

CoinGecko (No Auth Required)

| Endpoint | Data | |----------|------| | /search/trending | Top 15 trending coins | | /coins/markets | Top 100 by market cap with 24h changes |

Scoring: Trending coins get 2 points, movers with >3% change get 1 point.

Google News RSS (No Auth Required)

| Feed | Content | |------|---------| | Business News | General finance headlines | | Crypto Search | Bitcoin, Ethereum, crypto keywords |

Ticker Extraction: Uses regex patterns and company name mappings.

Yahoo Finance (No Auth Required)

| Page | Data | |------|------| | /gainers | Top gaining stocks | | /losers | Top losing stocks | | /most-active | Highest volume stocks |

Note: Requires gzip decompression.

Twitter/X (Auth Required)

Uses bird CLI for Twitter search.

Searches:

• stock OR $SPY OR $QQQ OR earnings
• bitcoin OR ethereum OR crypto OR $BTC

Twitter/X Setup

1. Install bird CLI

# macOS
brew install steipete/tap/bird

# npm
npm install -g @steipete/bird

2. Get Auth Tokens

Option A: Browser cookies (macOS)

1. Login to x.com in Safari/Chrome
2. Grant Terminal "Full Disk Access" in System Settings
3. Run bird whoami to verify

Option B: Manual extraction

1. Open x.com in Chrome
2. DevTools (F12) → Application → Cookies → x.com
3. Copy auth_token and ct0 values

3. Configure

Create .env file in the skill directory:

# /path/to/stock-analysis/.env
AUTH_TOKEN=your_auth_token_here
CT0=your_ct0_token_here

Or export as environment variables:

export AUTH_TOKEN="..."
export CT0="..."

4. Verify

bird whoami
# Should show: 🙋 @YourUsername

Scoring System

Each mention from a source adds points:

| Source | Points | |--------|--------| | CoinGecko Trending | 2 | | CoinGecko Movers | 1 | | Google News | 1 | | Yahoo Finance | 1 | | Twitter/X | 1 | | Reddit (high score) | 2 | | Reddit (normal) | 1 |

Symbols are ranked by total points across all sources.

Ticker Extraction

Patterns

# Cashtag: $AAPL
r'\$([A-Z]{1,5})\b'

# Parentheses: (AAPL)
r'\(([A-Z]{2,5})\)'

# Stock mentions: AAPL stock, AAPL shares
r'\b([A-Z]{2,5})(?:\'s|:|\s+stock|\s+shares)'

Company Mappings

{
    "Apple": "AAPL",
    "Microsoft": "MSFT",
    "Tesla": "TSLA",
    "Nvidia": "NVDA",
    "Bitcoin": "BTC",
    "Ethereum": "ETH",
    # ... etc
}

Crypto Keywords

{
    "bitcoin": "BTC",
    "ethereum": "ETH",
    "solana": "SOL",
    "dogecoin": "DOGE",
    # ... etc
}

Automation

Cron Job

# Daily at 8 AM
0 8 * * * cd /path/to/stock-analysis && python3 scripts/hot_scanner.py --json > cache/daily_scan.json

OpenClaw Integration

# Cron job config
name: "🔥 Daily Hot Scanner"
schedule:
  kind: cron
  expr: "0 8 * * *"
  tz: "Europe/Berlin"
payload:
  kind: agentTurn
  message: "Run hot scanner and summarize results"
  deliver: true
sessionTarget: isolated

Caching

Results are saved to:

• cache/hot_scan_latest.json — Most recent scan

Limitations

• Reddit: Blocked without OAuth (403). Requires API application.
• Twitter: Requires auth tokens, may expire.
• Yahoo: Sometimes rate-limited.
• Google News: RSS URLs may change.

Future Enhancements

• [ ] Reddit API integration (PRAW)
• [ ] StockTwits integration
• [ ] Google Trends
• [ ] Historical trend tracking
• [ ] Alert thresholds (notify when score > X)

Troubleshooting

Twitter not working

# Check auth
bird whoami

# Should see your username
# If not, re-export tokens

Yahoo 403 or gzip errors

The scanner handles gzip automatically. If issues persist, Yahoo may be rate-limiting.

No tickers found

Check that news headlines contain recognizable patterns. The scanner uses conservative extraction to avoid false positives.

File v6.1.0:docs/USAGE.md

Usage Guide

Practical examples for using Stock Analysis v6.0 in real scenarios.

Table of Contents

1. Basic Stock Analysis
2. Comparing Stocks
3. Crypto Analysis
4. Dividend Investing
5. Portfolio Management
6. Watchlist & Alerts
7. Performance Tips
8. Interpreting Results

---

Basic Stock Analysis

Single Stock

uv run scripts/analyze_stock.py AAPL

Output:

===========================================================================
STOCK ANALYSIS: AAPL (Apple Inc.)
Generated: 2024-02-01T10:30:00
===========================================================================

RECOMMENDATION: BUY (Confidence: 72%)

SUPPORTING POINTS:
• Beat by 8.2% - EPS $2.18 vs $2.01 expected
• Strong margin: 24.1%
• Analyst consensus: Buy with 12.3% upside (42 analysts)
• Momentum: RSI 58 (neutral)
• Sector: Technology uptrend (+5.2% 1m)

CAVEATS:
• Earnings in 12 days - high volatility expected
• High market volatility (VIX 24)

===========================================================================
DISCLAIMER: NOT FINANCIAL ADVICE.
===========================================================================

JSON Output

For programmatic use:

uv run scripts/analyze_stock.py AAPL --output json | jq '.recommendation, .confidence'

Verbose Mode

See what's happening under the hood:

uv run scripts/analyze_stock.py AAPL --verbose

---

Comparing Stocks

Side-by-Side Analysis

uv run scripts/analyze_stock.py AAPL MSFT GOOGL

Each stock gets a full analysis. Compare recommendations and confidence levels.

Sector Comparison

Compare stocks in the same sector:

# Banks
uv run scripts/analyze_stock.py JPM BAC WFC GS

# Tech
uv run scripts/analyze_stock.py AAPL MSFT GOOGL AMZN META

---

Crypto Analysis

Basic Crypto

uv run scripts/analyze_stock.py BTC-USD

Crypto-Specific Output:

• Market cap classification (large/mid/small)
• Category (Smart Contract L1, DeFi, etc.)
• BTC correlation (30-day)
• Momentum (RSI, price range)

Compare Cryptos

uv run scripts/analyze_stock.py BTC-USD ETH-USD SOL-USD

Supported Cryptos

BTC, ETH, BNB, SOL, XRP, ADA, DOGE, AVAX, DOT, MATIC,
LINK, ATOM, UNI, LTC, BCH, XLM, ALGO, VET, FIL, NEAR

Use -USD suffix: BTC-USD, ETH-USD, etc.

---

Dividend Investing

Analyze Dividend Stock

uv run scripts/dividends.py JNJ

Output:

============================================================
DIVIDEND ANALYSIS: JNJ (Johnson & Johnson)
============================================================

Current Price:    $160.50
Annual Dividend:  $4.76
Dividend Yield:   2.97%
Payment Freq:     quarterly
Ex-Dividend:      2024-02-15

Payout Ratio:     65.0% (moderate)
5Y Div Growth:    +5.8%
Consecutive Yrs:  62

SAFETY SCORE:     78/100
INCOME RATING:    GOOD

Safety Factors:
  • Moderate payout ratio (65%)
  • Good dividend growth (+5.8% CAGR)
  • Dividend Aristocrat (62+ years)

Dividend History:
  2023: $4.52
  2022: $4.36
  2021: $4.24
  2020: $4.04
  2019: $3.80
============================================================

Compare Dividend Stocks

uv run scripts/dividends.py JNJ PG KO MCD VZ T

Dividend Aristocrats Screen

Look for stocks with:

• Yield > 2%
• Payout < 60%
• Growth > 5%
• Consecutive years > 25

---

Portfolio Management

Create Portfolio

uv run scripts/portfolio.py create "Retirement"

Add Holdings

# Stocks
uv run scripts/portfolio.py add AAPL --quantity 100 --cost 150.00

# Crypto
uv run scripts/portfolio.py add BTC-USD --quantity 0.5 --cost 40000

View Portfolio

uv run scripts/portfolio.py show

Output:

Portfolio: Retirement
====================

Assets:
  AAPL     100 shares @ $150.00 = $15,000.00
           Current: $185.00 = $18,500.00 (+23.3%)
  
  BTC-USD  0.5 @ $40,000 = $20,000.00
           Current: $45,000 = $22,500.00 (+12.5%)

Total Cost:    $35,000.00
Current Value: $41,000.00
Total P&L:     +$6,000.00 (+17.1%)

Analyze Portfolio

# Full analysis of all holdings
uv run scripts/analyze_stock.py --portfolio "Retirement"

# With period returns
uv run scripts/analyze_stock.py --portfolio "Retirement" --period monthly

Rebalance Check

The analysis flags concentration warnings:

⚠️ CONCENTRATION WARNINGS:
   • AAPL: 45.1% (>30% of portfolio)

---

Watchlist & Alerts

Add to Watchlist

# Basic watch
uv run scripts/watchlist.py add NVDA

# With price target
uv run scripts/watchlist.py add NVDA --target 800

# With stop loss
uv run scripts/watchlist.py add NVDA --stop 600

# Alert on signal change
uv run scripts/watchlist.py add NVDA --alert-on signal

# All options
uv run scripts/watchlist.py add NVDA --target 800 --stop 600 --alert-on signal

View Watchlist

uv run scripts/watchlist.py list

Output:

{
  "success": true,
  "items": [
    {
      "ticker": "NVDA",
      "current_price": 725.50,
      "price_at_add": 700.00,
      "change_pct": 3.64,
      "target_price": 800.00,
      "to_target_pct": 10.27,
      "stop_price": 600.00,
      "to_stop_pct": -17.30,
      "alert_on_signal": true,
      "last_signal": "BUY",
      "added_at": "2024-01-15"
    }
  ],
  "count": 1
}

Check Alerts

# Check for triggered alerts
uv run scripts/watchlist.py check

# Format for notification (Telegram)
uv run scripts/watchlist.py check --notify

Alert Example:

📢 Stock Alerts

🎯 NVDA hit target! $802.50 >= $800.00
🛑 TSLA hit stop! $195.00 <= $200.00
📊 AAPL signal changed: HOLD → BUY

Remove from Watchlist

uv run scripts/watchlist.py remove NVDA

---

Performance Tips

Fast Mode

Skip slow analyses for quick checks:

# Skip insider trading + breaking news
uv run scripts/analyze_stock.py AAPL --fast

Speed comparison: | Mode | Time | What's Skipped | |------|------|----------------| | Default | 5-10s | Nothing | | --no-insider | 3-5s | SEC EDGAR | | --fast | 2-3s | Insider + News |

Batch Analysis

Analyze multiple stocks in one command:

uv run scripts/analyze_stock.py AAPL MSFT GOOGL AMZN META

Caching

Market context is cached for 1 hour:

• VIX, SPY, QQQ trends
• Fear & Greed Index
• VIX term structure
• Breaking news

Second analysis of different stock reuses cached data.

---

Interpreting Results

Recommendation Thresholds

| Score | Recommendation | |-------|----------------| | > +0.33 | BUY | | -0.33 to +0.33 | HOLD | | < -0.33 | SELL |

Confidence Levels

| Confidence | Meaning | |------------|---------| | > 80% | Strong conviction | | 60-80% | Moderate conviction | | 40-60% | Mixed signals | | < 40% | Low conviction |

Reading Caveats

Always read the caveats! They often contain critical information:

CAVEATS:
• Earnings in 5 days - high volatility expected    ← Timing risk
• RSI 78 (overbought) + near 52w high              ← Technical risk
• ⚠️ BREAKING NEWS: Fed emergency rate discussion

Archive v6.0.0: 10 files, 50773 bytes

Files: App-Plan.md (14708b), README.md (4321b), scripts/analyze_stock.py (89930b), scripts/dividends.py (13130b), scripts/portfolio.py (18897b), scripts/test_stock_analysis.py (11958b), scripts/watchlist.py (11542b), SKILL.md (5674b), TODO.md (12848b), _meta.json (133b)

Archive v5.0.0: 7 files, 41538 bytes

Files: App-Plan.md (14708b), README.md (3295b), scripts/analyze_stock.py (88970b), scripts/portfolio.py (18897b), SKILL.md (8381b), TODO.md (12848b), _meta.json (133b)

Archive v4.0.0: 4 files, 25321 bytes

Files: scripts/analyze_stock.py (69140b), SKILL.md (6322b), TODO.md (12243b), _meta.json (133b)

Archive v3.5.0: 4 files, 20870 bytes

Files: scripts/analyze_stock.py (55960b), SKILL.md (4867b), TODO.md (12243b), _meta.json (133b)

Archive v3.0.0: 3 files, 15312 bytes

Files: scripts/analyze_stock.py (53567b), SKILL.md (4829b), _meta.json (133b)

Archive v2.0.0: 3 files, 11767 bytes

Files: scripts/analyze_stock.py (39895b), SKILL.md (3674b), _meta.json (133b)

Archive v1.0.1: 3 files, 7117 bytes

Files: scripts/analyze_stock.py (20374b), SKILL.md (2532b), _meta.json (133b)

Archive v1.0.0: 3 files, 6902 bytes

Files: scripts/analyze_stock.py (20374b), SKILL.md (2080b), _meta.json (133b)