Stock Analysis

Stock Analysis (v5.0)

Analyze US stocks and cryptocurrencies using Yahoo Finance data. Includes portfolio management, crypto support, and periodic analysis.

Quick Start

IMPORTANT: Pass ONLY the stock ticker symbol(s) as arguments. Do NOT add extra text, headers, or formatting in the command.

Analyze a single ticker:

uv run {baseDir}/scripts/analyze_stock.py AAPL
uv run {baseDir}/scripts/analyze_stock.py MSFT --output json

Compare multiple tickers:

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

Cryptocurrency Analysis (v5.0)

Analyze top 20 cryptocurrencies by market cap:

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

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

Crypto Analysis Dimensions:

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

Portfolio Management (v5.0)

Create and manage portfolios with mixed assets (stocks + crypto):

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

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

# View holdings with current P&L
uv run {baseDir}/scripts/portfolio.py show

# Update/remove assets
uv run {baseDir}/scripts/portfolio.py update AAPL --quantity 150
uv run {baseDir}/scripts/portfolio.py remove BTC-USD

# List/delete portfolios
uv run {baseDir}/scripts/portfolio.py list
uv run {baseDir}/scripts/portfolio.py delete "My Portfolio"

Portfolio Storage: ~/.clawdbot/skills/stock-analysis/portfolios.json

Portfolio Analysis (v5.0)

Analyze all assets in a portfolio with optional period returns:

# Analyze portfolio
uv run {baseDir}/scripts/analyze_stock.py --portfolio "My Portfolio"

# With period returns (daily/weekly/monthly/quarterly/yearly)
uv run {baseDir}/scripts/analyze_stock.py --portfolio "My Portfolio" --period weekly
uv run {baseDir}/scripts/analyze_stock.py -p "My Portfolio" --period monthly

Portfolio Summary includes:

• Total cost, current value, P&L
• Period return (if specified)
• Concentration warnings (>30% in single asset)
• Recommendation summary (BUY/HOLD/SELL counts)

Examples:

• ✅ CORRECT: uv run {baseDir}/scripts/analyze_stock.py BAC
• ✅ CORRECT: uv run {baseDir}/scripts/analyze_stock.py BTC-USD
• ❌ WRONG: uv run {baseDir}/scripts/analyze_stock.py === BANK OF AMERICA (BAC) - Q4 2025 EARNINGS ===
• ❌ WRONG: uv run {baseDir}/scripts/analyze_stock.py "Bank of America"

Use the ticker symbol only (e.g., BAC, not "Bank of America"). For crypto, use the -USD suffix (e.g., BTC-USD).

Analysis Components

The script evaluates eight key dimensions:

1. Earnings Surprise (30% weight): Actual vs expected EPS, revenue beats/misses 2. Fundamentals (20% weight): P/E ratio, profit margins, revenue growth, debt levels 3. Analyst Sentiment (20% weight): Consensus ratings, price target vs current price 4. Historical Patterns (10% weight): Past earnings reactions, volatility 5. Market Context (10% weight): VIX, SPY/QQQ trends, market regime 6. Sector Performance (15% weight): Stock vs sector comparison, sector trends 7. Momentum (15% weight): RSI, 52-week range, volume, relative strength 8. Sentiment Analysis (10% weight): Fear/Greed Index, short interest, VIX term structure, insider trading, put/call ratio

Sentiment Sub-Indicators:

• Fear & Greed Index (CNN): Contrarian signal (extreme fear = buy opportunity, extreme greed = caution)
• Short Interest: High shorts + squeeze potential = bullish; justified shorts = bearish
• VIX Term Structure: Contango = complacency/bullish; backwardation = stress/bearish
• Insider Activity: Net buying/selling from SEC Form 4 filings (90-day window)
• Put/Call Ratio: High ratio = excessive fear/bullish; low ratio = complacency/bearish

Weights auto-normalize if some components unavailable.

Special Timing Checks:

• Pre-earnings warning (< 14 days): Recommends HOLD instead of BUY
• Post-earnings spike detection (> 15% in 5 days): Flags "gains priced in"
• Overbought conditions (RSI > 70 + near 52w high): Reduces confidence

Timing Warnings & Risk Flags

The script detects high-risk scenarios:

Earnings Timing

• Pre-Earnings Period: If earnings < 14 days away, BUY signals become HOLD
• Post-Earnings Spike: If stock up > 15% in 5 days after earnings, warns "gains may be priced in"

Technical Risk

• Overbought Conditions: RSI > 70 + near 52-week high = high-risk entry

Market Risk

• High VIX: Market fear (VIX > 30) reduces confidence in BUY signals
• Risk-Off Mode (v4.0.0): When safe-havens (GLD, TLT, UUP) rise together, reduces BUY confidence by 30%
• Detects flight to safety across gold, treasuries, and USD
• Triggers when GLD ≥ +2%, TLT ≥ +1%, UUP ≥ +1% (5-day change)

Sector Risk

• Sector Weakness: Stock may look good but sector is rotating out

Geopolitical Risk (v4.0.0)

The script now scans breaking news (last 24h) for crisis keywords and automatically flags affected stocks:

• Taiwan Conflict: Semiconductors (NVDA, AMD, TSM, INTC, etc.) → 30% confidence penalty
• China Tensions: Tech/Consumer (AAPL, QCOM, NKE, SBUX, etc.) → 30% confidence penalty
• Russia-Ukraine: Energy/Materials (XOM, CVX, MOS, CF, etc.) → 30% confidence penalty
• Middle East: Oil/Defense (XOM, LMT, RTX, etc.) → 30% confidence penalty
• Banking Crisis: Financials (JPM, BAC, WFC, C, etc.) → 30% confidence penalty

If a ticker is not in the affected list but its sector is exposed, applies a 15% confidence penalty.

Example Alert:

⚠️ SECTOR RISK: Tech supply chain and consumer market exposure (detected: china, tariff)

Breaking News Alerts (v4.0.0)

• Scans Google News RSS for crisis keywords (war, recession, sanctions, disasters, etc.)
• Displays up to 2 breaking news alerts in caveats (last 24 hours)
• Uses 1-hour cache to avoid excessive API calls

Output Format

Default (text): Concise buy/hold/sell signal with 3-5 bullet points and caveats

JSON: Structured data with scores, metrics, and raw data for further analysis

Limitations

• Data freshness: Yahoo Finance may lag 15-20 minutes
• Sentiment data staleness:
• Short interest data lags ~2 weeks (FINRA reporting schedule)
• Insider trades may lag filing by 2-3 days
• VIX term structure only updates during futures trading hours
• Breaking news limitations (v4.0.0):
• Google News RSS may lag by 15-60 minutes
• Keyword matching may have false positives/negatives
• Does not analyze sentiment, only detects keywords
• 1-hour cache means alerts may be slightly stale
• Missing data: Not all stocks have analyst coverage, options chains, or complete fundamentals
• Execution time: 3-5s per stock with async parallel fetching and caching (shared indicators cached for 1h)
• Disclaimer: All outputs include prominent "not financial advice" warning
• US markets only: Non-US tickers may have incomplete data

Error Handling

The script gracefully handles:

• Invalid tickers → Clear error message
• Missing analyst data → Signal based on available metrics only
• API failures → Retry with exponential backoff, fail after 3 attempts

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):

---

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

---

Success Metrics (Year 1)

---

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)

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.

Stock Analysis v5.0

Analyze stocks and cryptocurrencies with portfolio management, periodic reports, and 8-dimension analysis.

Features

Quick Start

Analyze Stocks

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

Analyze Crypto

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

Portfolio Management

# Create and manage portfolios
uv run scripts/portfolio.py create "My Portfolio"
uv run scripts/portfolio.py add AAPL --quantity 100 --cost 150
uv run scripts/portfolio.py add BTC-USD --quantity 0.5 --cost 40000
uv run scripts/portfolio.py show

# Analyze portfolio
uv run scripts/analyze_stock.py --portfolio "My Portfolio"
uv run scripts/analyze_stock.py --portfolio "My Portfolio" --period weekly

Supported Cryptocurrencies (Top 20)

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

Analysis Dimensions

Stocks (8 dimensions)

1. Earnings Surprise - EPS beats/misses 2. Fundamentals - P/E, margins, growth, debt 3. Analyst Sentiment - Ratings, price targets 4. Historical Patterns - Past earnings reactions 5. Market Context - VIX, SPY/QQQ trends 6. Sector Performance - Relative strength 7. Momentum - RSI, 52-week range 8. Sentiment - Fear/Greed, short interest, insider trading

Crypto (3 dimensions)

1. Crypto Fundamentals - Market cap, category, BTC correlation 2. Momentum - RSI, price range 3. Market Context - General market regime

Risk Features

• Breaking News Alerts - Scans for crisis keywords (war, recession, sanctions)
• Geopolitical Risk - Taiwan, China, Russia, Middle East, banking crisis detection
• Safe-Haven Tracking - GLD, TLT, UUP for risk-off detection
• Concentration Warnings - Alerts when >30% in single asset

Portfolio Storage

Portfolios stored at: ~/.clawdbot/skills/stock-analysis/portfolios.json

Version History

• v5.0.0 - Portfolio management, crypto support, periodic analysis
• v4.1.0 - Insider trading via edgartools, market context caching
• v4.0.0 - Geopolitical risk, breaking news, safe-haven detection
• v3.0.0 - Sentiment analysis (5 indicators)
• v2.0.0 - Market context, sector, momentum
• v1.0.0 - Initial release

Data Sources

• Yahoo Finance - Price, fundamentals, earnings
• CNN Fear & Greed - Market sentiment
• SEC EDGAR - Insider trading (Form 4)
• Google News RSS - Breaking news

---

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

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 (stock-analysis@clawd.bot)
• ✅ 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:

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