1# Stock Analysis - Future Enhancements
2 
3## Roadmap Overview
4 
5### v4.0.0 (Current) - Geopolitical Risk & News Sentiment
6✅ 8 analysis dimensions with Fear/Greed, short interest, VIX structure, put/call ratio
7✅ Safe-haven indicators (GLD, TLT, UUP) with risk-off detection
8✅ Breaking news alerts via Google News RSS
9✅ Geopolitical risk mapping (Taiwan, China, Russia, Middle East, Banking)
10✅ Sector-specific crisis flagging with confidence penalties
11✅ 1h caching for shared indicators (Fear/Greed, VIX structure, breaking news)
12✅ Async parallel sentiment fetching (5 indicators with 10s timeouts)
13 
14### v5.0.0 (Current) - Portfolio & Crypto
15✅ Portfolio management (create, add, remove, show assets)
16✅ Cryptocurrency support (Top 20 by market cap)
17✅ Portfolio analysis with --portfolio flag
18✅ Periodic returns (--period daily/weekly/monthly/quarterly/yearly)
19✅ Concentration warnings (>30% single asset)
20✅ Crypto fundamentals (market cap, category, BTC correlation)
21 
22### v4.1.0 - Performance & Completeness
23✅ Full insider trading parsing via edgartools (Task #1)
24✅ Market context caching with 1h TTL (Task #3b)
25🔧 SEC EDGAR rate limit monitoring (Task #4 - low priority)
26 
27### Future (v6.0+)
28💡 Research phase: Social sentiment, fund flows, on-chain metrics
29 
30---
31 
32## Sentiment Analysis Improvements
33 
34### 1. Implement Full Insider Trading Parsing
35**Status**: ✅ DONE
36**Priority**: Medium
37**Effort**: 2-3 hours
38 
39**Current State**:
40- ✅ `get_insider_activity()` fetches Form 4 filings via edgartools
41- ✅ SEC identity configured (`[email protected]`)
42- ✅ Aggregates buys/sells over 90-day window
43- ✅ Scoring logic: strong buying (+0.8), moderate (+0.4), neutral (0), moderate selling (-0.4), strong (-0.8)
44 
45**Tasks**:
46- [ ] Research edgartools API for Form 4 parsing
47- [ ] Implement transaction aggregation (90-day window)
48- [ ] Calculate net shares bought/sold
49- [ ] Calculate net value in millions USD
50- [ ] Apply scoring logic:
51  - Strong buying (>100K shares or >$1M): +0.8
52  - Moderate buying (>10K shares or >$0.1M): +0.4
53  - Neutral: 0
54  - Moderate selling: -0.4
55  - Strong selling: -0.8
56- [ ] Add error handling for missing/incomplete filings
57- [ ] Test with multiple tickers (BAC, TSLA, AAPL)
58- [ ] Verify SEC rate limit compliance (10 req/s)
59 
60**Expected Impact**:
61- Insider activity detection for 4th sentiment indicator
62- Increase from 3/5 to 4/5 indicators typically available
63 
64---
65 
66### 2. Add Parallel Async Fetching
67**Status**: ✅ DONE (sentiment indicators)
68**Priority**: High
69**Effort**: 4-6 hours
70 
71**Current State**:
72- ✅ Sentiment indicators fetched in parallel via `asyncio.gather()`
73- ✅ 10s timeout per indicator
74- Main data fetches (yfinance) still sequential (acceptable)
75 
76**Tasks**:
77- [ ] Convert sentiment helper functions to async
78  - [ ] `async def get_fear_greed_index()`
79  - [ ] `async def get_short_interest(data)`
80  - [ ] `async def get_vix_term_structure()`
81  - [ ] `async def get_insider_activity(ticker)`
82  - [ ] `async def get_put_call_ratio(data)`
83- [ ] Update `analyze_sentiment()` to use `asyncio.gather()`
84- [ ] Handle yfinance thread safety (may need locks)
85- [ ] Add timeout per indicator (10s max)
86- [ ] Test with multiple stocks in sequence
87- [ ] Measure actual runtime improvement
88- [ ] Update SKILL.md with new runtime (target: 3-4s)
89 
90**Expected Impact**:
91- Reduce runtime from 6-10s to 3-4s per stock
92- Better user experience for multi-stock analysis
93 
94---
95 
96### 3. Add Caching for Shared Indicators
97**Status**: ✅ DONE (sentiment + breaking news)
98**Priority**: Medium
99**Effort**: 2-3 hours
100 
101**Current State**:
102- ✅ Fear & Greed Index cached (1h TTL)
103- ✅ VIX term structure cached (1h TTL)
104- ✅ Breaking news cached (1h TTL)
105- ✅ Market context (VIX/SPY/QQQ/GLD/TLT/UUP) cached (1h TTL)
106 
107**Tasks**:
108- [ ] Design cache structure (simple dict or functools.lru_cache)
109- [ ] Implement TTL (time-to-live):
110  - Fear & Greed: 1 hour
111  - VIX structure: 1 hour
112  - Short interest: No cache (per-stock)
113  - Insider activity: No cache (per-stock)
114  - Put/Call ratio: No cache (per-stock)
115- [ ] Add cache invalidation logic
116- [ ] Add verbose logging for cache hits/misses
117- [ ] Test multi-stock analysis (e.g., `BAC TSLA AAPL`)
118- [ ] Measure performance improvement
119- [ ] Document caching behavior in SKILL.md
120 
121**Expected Impact**:
122- Multi-stock analysis faster (e.g., 3 stocks: 18-30s → 10-15s)
123- Reduced API calls to Fear/Greed and VIX data sources
124- Same-session analysis efficiency
125 
126---
127 
128### 4. Monitor SEC EDGAR Rate Limits
129**Status**: Not Started
130**Priority**: Low (until insider trading implemented)
131**Effort**: 1-2 hours
132 
133**Current State**:
134- SEC EDGAR API has 10 requests/second rate limit
135- No rate limit tracking or logging
136- edgartools may handle rate limiting internally
137 
138**Tasks**:
139- [ ] Research edgartools rate limit handling
140- [ ] Add request counter/tracker if needed
141- [ ] Implement exponential backoff on 429 errors
142- [ ] Add logging for rate limit hits
143- [ ] Test with high-volume scenarios (10+ stocks in quick succession)
144- [ ] Document rate limit behavior
145- [ ] Add error message if rate limited: "SEC API rate limited, try again in 1 minute"
146 
147**Expected Impact**:
148- Robust handling of SEC API limits in production
149- Clear user feedback if limits hit
150- Prevent API blocking/banning
151 
152---
153 
154## Stock Analysis 4.0: Geopolitical Risk & News Sentiment
155 
156### What's Currently Missing
157 
158The current implementation captures:
159- ✅ VIX (general market fear)
160- ✅ SPY/QQQ trends (market direction)
161- ✅ Sector performance
162 
163What we **don't** have yet:
164- ❌ Geopolitical risk indicators
165- ❌ News sentiment analysis
166- ❌ Sector-specific crisis flags
167 
168---
169 
170### 7. Geopolitical Risk Index
171**Status**: ✅ DONE (keyword-based)
172**Priority**: High
173**Effort**: 8-12 hours
174 
175**Proposed Approach**:
176Option A: Use GPRD (Geopolitical Risk Daily Index) from policyuncertainty.com
177Option B: Scan news APIs (NewsAPI, GDELT) for geopolitical keywords
178 
179**Tasks**:
180- [ ] Research free geopolitical risk data sources
181  - [ ] Check policyuncertainty.com API availability
182  - [ ] Evaluate NewsAPI free tier limits
183  - [ ] Consider GDELT Project (free, comprehensive)
184- [ ] Design risk scoring system (0-100 scale)
185- [ ] Implement data fetching with caching (4-hour TTL)
186- [ ] Map risk levels to sentiment scores:
187  - Low risk (0-30): +0.2 (bullish)
188  - Moderate risk (30-60): 0 (neutral)
189  - High risk (60-80): -0.3 (caution)
190  - Extreme risk (80-100): -0.5 (bearish)
191- [ ] Add to sentiment analysis as 6th indicator
192- [ ] Test with historical crisis periods
193- [ ] Update SKILL.md with geopolitical indicator
194 
195**Expected Impact**:
196- Early warning for market-wide risk events
197- Better context for earnings-season volatility
198- Complement to VIX (VIX is reactive, geopolitical is predictive)
199 
200**Example Output**:
201```
202⚠️ GEOPOLITICAL RISK: HIGH (72/100)
203   Context: Elevated Taiwan tensions detected
204   Market Impact: Risk-off sentiment likely
205```
206 
207---
208 
209### 8. Sector-Specific Crisis Mapping
210**Status**: ✅ DONE
211**Priority**: High
212**Effort**: 6-8 hours
213 
214**Current Gap**:
215- No mapping between geopolitical events and affected sectors
216- No automatic flagging of at-risk holdings
217 
218**Proposed Risk Mapping**:
219 
220| Geopolitical Event | Affected Sectors | Example Tickers |
221|-------------------|------------------|-----------------|
222| Taiwan conflict | Semiconductors | NVDA, AMD, TSM, INTC |
223| Russia-Ukraine | Energy, Agriculture | XLE, MOS, CF, NTR |
224| Middle East escalation | Oil, Defense | XOM, CVX, LMT, RTX |
225| China tensions | Tech supply chain, Retail | AAPL, QCOM, NKE, SBUX |
226| Banking crisis | Financials | JPM, BAC, WFC, C |
227 
228**Tasks**:
229- [ ] Build event → sector → ticker mapping database
230- [ ] Implement keyword detection in news feeds:
231  - "Taiwan" + "military" → Semiconductors ⚠️
232  - "Russia" + "sanctions" → Energy ⚠️
233  - "Iran" + "attack" → Oil, Defense ⚠️
234  - "China" + "tariffs" → Tech, Consumer ⚠️
235- [ ] Add sector exposure check to analysis
236- [ ] Generate automatic warnings in output
237- [ ] Apply confidence penalty for high-risk sectors
238- [ ] Test with historical crisis events
239- [ ] Document in SKILL.md
240 
241**Expected Impact**:
242- Automatic detection of sector-specific risks
243- Clear warnings for exposed holdings
244- Reduced false positives (only flag relevant sectors)
245 
246**Example Output**:
247```
248⚠️ SECTOR RISK ALERT: Semiconductors
249   Event: Taiwan military exercises (elevated tensions)
250   Impact: NVDA HIGH RISK - supply chain exposure
251   Recommendation: HOLD → downgraded from BUY
252```
253 
254---
255 
256### 9. Breaking News Check
257**Status**: ✅ DONE
258**Priority**: Medium
259**Effort**: 4-6 hours
260 
261**Current Gap**:
262- No real-time news scanning before analysis
263- User might get stale recommendation during breaking events
264 
265**Proposed Solution**:
266- Scan Google News or Reuters RSS before analysis
267- Flag high-impact keywords within last 24 hours
268 
269**Tasks**:
270- [ ] Choose news source (Google News RSS, Reuters API, or NewsAPI)
271- [ ] Implement news fetching with 24-hour lookback
272- [ ] Define crisis keywords:
273  - **War/Conflict**: "war", "invasion", "military strike", "attack"
274  - **Economic**: "recession", "crisis", "collapse", "default"
275  - **Regulatory**: "sanctions", "embargo", "ban", "investigation"
276  - **Natural disaster**: "earthquake", "hurricane", "pandemic"
277- [ ] Add ticker-specific news check (company name + keywords)
278- [ ] Generate automatic caveat in output
279- [ ] Cache news check results (1 hour TTL)
280- [ ] Add `--skip-news` flag for offline mode
281- [ ] Test with historical crisis dates
282- [ ] Document in SKILL.md
283 
284**Expected Impact**:
285- Real-time awareness of breaking events
286- Automatic caveats during high volatility
287- User protection from stale recommendations
288 
289**Example Output**:
290```
291⚠️ BREAKING NEWS ALERT (last 6 hours):
292   "Fed announces emergency rate hike"
293   Impact: Market-wide volatility expected
294   Caveat: Analysis may be outdated - rerun in 24h
295```
296 
297---
298 
299### 10. Safe-Haven Indicators
300**Status**: ✅ DONE
301**Priority**: Medium
302**Effort**: 3-4 hours
303 
304**Current Gap**:
305- No detection of "risk-off" market regime
306- VIX alone is insufficient (measures implied volatility, not capital flows)
307 
308**Proposed Indicators**:
309- Gold (GLD) - Flight to safety
310- US Treasuries (TLT) - Bond market fear
311- USD Index (UUP) - Dollar strength during crisis
312 
313**Risk-Off Detection Logic**:
314```
315IF GLD +2% AND TLT +1% AND UUP +1% (all rising together)
316THEN Market Regime = RISK-OFF
317```
318 
319**Tasks**:
320- [ ] Fetch GLD, TLT, UUP price data (5-day change)
321- [ ] Implement risk-off detection algorithm
322- [ ] Add to market context analysis
323- [ ] Apply broad risk penalty:
324  - Risk-off detected → Reduce all BUY confidence by 30%
325  - Add caveat: "Market in risk-off mode - defensive positioning recommended"
326- [ ] Test with historical crisis periods (2008, 2020, 2022)
327- [ ] Add verbose output for safe-haven movements
328- [ ] Document in SKILL.md
329 
330**Expected Impact**:
331- Detect market-wide flight to safety
332- Automatic risk reduction during panics
333- Complement geopolitical risk scoring
334 
335**Example Output**:
336```
337🛡️ SAFE-HAVEN ALERT: Risk-off mode detected
338   - Gold (GLD): +3.2% (5d)
339   - Treasuries (TLT): +2.1% (5d)
340   - USD Index: +1.8% (5d)
341   Recommendation: Reduce equity exposure, favor defensives
342```
343 
344---
345 
346## General Improvements
347 
348### 11. Add Social Sentiment (Future Phase)
349**Status**: Deferred
350**Priority**: Low
351**Effort**: 8-12 hours
352 
353**Notes**:
354- Requires free API (Twitter/Reddit alternatives?)
355- Most sentiment APIs are paid (StockTwits, etc.)
356- Research needed for viable free sources
357 
358### 12. Add Fund Flows (Future Phase)
359**Status**: Deferred
360**Priority**: Low
361**Effort**: 6-8 hours
362 
363**Notes**:
364- Requires ETF flow data
365- May need paid data source
366- Research free alternatives
367 
368---
369 
370## Implementation Priorities
371 
372### v4.1.0 Complete
373- ✅ Task #1 - Insider trading parsing via edgartools
374- ✅ Task #3b - Market context caching (1h TTL)
375- 🔧 Task #4 - SEC EDGAR rate limits (low priority, only if hitting limits)
376 
377### Completed in v4.0.0
378- ✅ Task #2 - Async parallel fetching (sentiment)
379- ✅ Task #3 - Caching for shared indicators (sentiment + news)
380- ✅ Task #7 - Geopolitical risk (keyword-based)
381- ✅ Task #8 - Sector-specific crisis mapping
382- ✅ Task #9 - Breaking news check
383- ✅ Task #10 - Safe-haven indicators
384 
385---
386 
387## Version History
388 
389- **v5.0.0** (2026-01-16): Portfolio management, cryptocurrency support (Top 20), periodic analysis
390- **v4.1.0** (2026-01-16): Full insider trading parsing via edgartools, market context caching
391- **v4.0.0** (2026-01-15): Geopolitical risk, breaking news, safe-haven detection, sector crisis mapping
392- **v3.0.0** (2026-01-15): Sentiment analysis added with 5 indicators (3-4 typically working)
393- **v2.0.0**: Market context, sector performance, earnings timing, momentum
394- **v1.0.0**: Initial release with earnings, fundamentals, analysts, historical
395