---
name: stock-analysis
description: Analyze stocks and cryptocurrencies using LongPort (primary, HK/US/CN) + Yahoo Finance (fallback, US only) data. Supports 8-dimension stock scoring, portfolio management, watchlists with alerts, dividend analysis, 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 go mainstream. Includes unified data layer with graceful Yahoo fallback.
version: 6.4.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.3

Analyze US stocks and cryptocurrencies with **LongPort (primary) + Yahoo Finance (fallback)** data sources.

## What's New in v6.4

- 🆕 **DCA Ladder Monitoring** — Automated buy signals when prices hit ladder tiers
  - Position config JSON with 3-tier price ladders + lot sizes
  - Monitor script checks prices vs targets, silent when no triggers
  - 5 cron jobs: HK market 2x/day, US market 2x/day, daily morning brief
  - Status tracking: mark tiers as "done" after purchase
  - See `references/dca-ladder-monitoring.md`
- 🆕 **Autonomous workflow** — Full analysis pipeline runs without asking user permission
- 🆕 **DCA 6-dimension scoring** — Yield + PE + PB + Price Position + YTD Dip + Safety
  - See `references/dca-screener.md`

## What's New in v6.3

- 🆕 **LongPort Data Source** — Primary data for HK/US/CN stocks
  - Real-time quotes, PE, PB, EPS, BPS, dividend yield
  - Market cap, turnover rate, volume ratio
  - Full Hong Kong and A-share coverage
- 🆕 **Unified Data Layer** — `data_source.py` merges LongPort + Yahoo
  - LongPort: valuation metrics, realtime quotes
  - Yahoo: operating margins, ROE, analyst data, earnings history
- 🆕 **Valuation Analysis** — `analyze_stock_unified.py`
  - PE/PB/Dividend scoring (-1 to +1)
  - Weighted overall score
  - BUY/HOLD/SELL recommendations

## 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

### Valuation Analysis (NEW v6.3) — LongPort Primary + 8-Dimension Scoring
```bash
# Single stock valuation
uv run {baseDir}/scripts/analyze_stock_unified.py O

# Multiple stocks comparison
uv run {baseDir}/scripts/analyze_stock_unified.py O 823.HK MAIN JEPI NLY

# Hong Kong stocks
uv run {baseDir}/scripts/analyze_stock_unified.py 823.HK 778.HK 0405.HK

# Fast mode (skip slow analyses)
uv run {baseDir}/scripts/analyze_stock_unified.py O --fast

# JSON output
uv run {baseDir}/scripts/analyze_stock_unified.py O --output json
```

**8-Dimension Scoring System:**
- Fundamentals (40%): PE, PB, dividend yield, margins, ROE, debt
- Valuation (30%): PE/PB/dividend relative to thresholds
- Momentum (20%): RSI, volume ratio, price change
- Market Cap (10%): Large-cap stability vs small-cap risk

**Recommendation Thresholds:**
- Score > 0.3: BUY (High confidence)
- Score > 0.0: BUY (Moderate confidence)
- Score > -0.3: HOLD
- Score < -0.3: SELL

### Legacy Analysis (Yahoo Finance)
```bash
# 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)
```bash
# 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)
```bash
# 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
```bash
# 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)
```bash
# 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)
```bash
# 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` |

## Data Source Architecture (v6.3)

**Primary:** LongPort SDK — PE, PB, EPS, BPS, dividend yield, market cap, realtime quotes, HK/CN coverage
**Fallback:** Yahoo Finance — operating margins, ROE, debt ratios, analyst data, earnings history

### Files
| File | Purpose |
|------|---------|
| `scripts/data_source.py` | Unified data layer: LongPort primary + Yahoo fallback |
| `scripts/analyze_stock_unified.py` | 8-dimension analysis using unified data source |
| `scripts/analyze_stock.py` | Original Yahoo-only analysis (unchanged) |
| `references/valuation-quickstart.md` | Quick reference for valuation commands |
| `references/dca-ladder-monitoring.md` | DCA ladder monitoring: config, script, cron setup |

### Yahoo Fallback Pattern
Yahoo data is **optional** — if it fails (rate limiting, timeout), LongPort data alone is sufficient for core analysis. The `merge_data()` function handles this gracefully:
- LongPort fails → use Yahoo
- Yahoo fails → use LongPort only
- Both fail → return None
- Analysis functions return None on error → skipped in scoring

**User preference:** Yahoo data failures must NEVER block the overall analysis. Always degrade gracefully.
**User preference:** Do NOT simplify scoring systems. The 8-dimension scoring (earnings, fundamentals, analysts, historical, market context, sector, momentum, sentiment) must be preserved. Simple PE/PB/dividend scoring is insufficient — users want the full framework.

### DCA Screening (阶梯式买入) — High Dividend Candidates
```bash
# Uses calc_indexes with 5-dimension scoring: yield + PE + PB + volatility + YTD dip
# See references/dca-screening.md for full candidate list and scoring framework
```

## DCA (Dollar-Cost Averaging / 阶梯式买入) Screener

When user asks about DCA, 阶梯式买入, 分批建仓, or drip-feeding into stocks:

1. **Screen candidates** via LongPort `calc_indexes` with `DividendRatioTtm` + `TotalMarketValue` + `PeTtmRatio` + `PbRatio` (see `references/dca-screener.md`)
2. **Score with 6-dimension DCA model** (different from the 8-dimension earnings model):
   - Dividend yield (25pts) — higher = better
   - PE valuation (20pts) — sweet spot 5-12
   - PB value (15pts) — below 1 is great
   - Price position in 60-day range (15pts) — lower = better entry
   - YTD drawdown (15pts) — negative = buying opportunity
   - Safety/sustainability (10pts) — profitable + asset-backed + reasonable yield
3. **Generate price ladder**: 3 tiers — current price, 20-day support, 60-day low × 0.98
4. **Present visually**: emoji grades (🔥≥70, ⭐≥55, ✅<55), table format

See `references/dca-screener.md` for the full scoring methodology and script template.

## DCA Ladder Monitoring (阶梯买入自动监控)

After screening DCA candidates, set up automated price monitoring: config JSON → monitor script → cron jobs. When prices hit ladder tiers, push buy signals with exact share counts.

Full workflow: `references/dca-ladder-monitoring.md`

```
~/.hermes/scripts/dca_positions.json  ←  positions + ladder + budget
~/.hermes/scripts/dca_monitor.py      ←  price checker (silent when no triggers)
cron jobs (5x)                        ←  HK 10:00+15:00, US 22:30+02:00, 晨报 9:00
```

Key interactions: "我买了XX T1" → mark tier done | "调整价位" → edit JSON | "加一只" → add position | "设置预算" → recalc lots | "暂停DCA" → pause crons

## Workflow Preference

**CRITICAL — Autonomous analysis**: When user asks to analyze stocks, screen candidates, or find DCA targets, DO the full analysis immediately. Do NOT ask "should I run X?" or "want me to check Y?". User explicitly corrected: "你要自主去分析，我的风格你知道了嘛？". This means: run screens, pull data from LongPort, score, generate price ladders, present results — all in one shot. Only clarify if genuinely ambiguous (which market? which budget?). The user expects proactive execution, not permission-seeking.

## Pitfalls

- **Yahoo data fault tolerance**: Yahoo Finance frequently rate-limits or fails. The unified data layer (`data_source.py`, `analyze_stock_unified.py`) treats LongPort as primary and Yahoo as optional supplement. If Yahoo fails, analysis MUST still complete with LongPort data only. Never let a Yahoo failure block or crash the analysis. Each Yahoo-dependent field (operating_margin, roe, analyst ratings, earnings_history) is optional — check for None before using.
- **Keep full 8-dimension scoring**: User explicitly requires the full 8-dimension scoring system (Earnings, Fundamentals, Analysts, Historical, Market Context, Sector, Momentum, Sentiment). Do NOT simplify to PE/PB/dividend-only scoring. Simple scoring is insufficient — users want the full framework.
- **Decimal conversion**: LongPort returns `decimal.Decimal` for market_cap and some fields. Always `float()` before arithmetic.
- **uv not available**: If `uv run` fails with "command not found", install via `curl -LsSf https://astral.sh/uv/install.sh | sh` or fall back to `python3` directly with `pip3 install yfinance requests`. The analyze_stock_unified.py script needs uv; analyze_stock.py can run with plain python3 if yfinance is installed.
- **Yahoo Finance dead tickers**: Some tickers (especially BDCs, mREITs, small caps) fail on Yahoo Finance with "Invalid ticker or data unavailable". Always have LongPort as primary fallback — write a direct LongPort script if the unified scripts fail.
- **uv not installed**: All `uv run` scripts require `uv`. Install: `curl -LsSf https://astral.sh/uv/install.sh | sh`.
- **HK stocks incomplete on Yahoo**: Yahoo Finance coverage for HK stocks is spotty. For HK analysis, LongPort is primary.
- **Symbol format**: LongPort needs `TICKER.US` or `CODE.HK`. The data layer auto-converts bare tickers like `O` to `O.US`.
- **Monthly dividend stocks**: User frequently asks about monthly dividend stocks (US + HK). See `references/monthly-dividend-stocks.md`.

## 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.
