sophhub 0.4.19 → 0.4.21

package/skills/sophnet-stock/src/docs/CONCEPT.md

@@ -1,233 +1,233 @@
-# 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. 📈
+# 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. 📈