@v587d/capital-generation 2.6.5 → 2.7.1

package/selected-skills/InvestSkill/plugins/us-stock-analysis/skills/stock-screener/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: stock-screener
+description: Screen and rank multiple US stocks across valuation, quality, momentum, sentiment, and growth dimensions
+---
+
+# Stock Screener
+
+## ⚠️ Data Verification — Do This Before Any Analysis
+
+Before running any analysis, always retrieve the latest market data for the ticker:
+
+1. **Fetch current price** — get the live price, 52-week range, and market cap through the host's own data path. In a host that splits roles, delegate the request with an exact brief (ticker, fields, as-of date) rather than searching from this step. Never assume a price from training data.
+2. **Confirm key figures** — recent earnings, revenue, key ratios (P/E, P/S, etc.) as applicable to this skill.
+3. **State your data source** — fill in the `Data & Sources` header (next section) so the origin, as-of date, retrieval path, and confidence of every figure are explicit at the top of the output.
+4. **Stop on missing data** — if a figure cannot be retrieved through the host's data path, name what is missing and stop; the analysis does not run on remembered values:
+
+> ⚠️ **Data unavailable.** <list the figures this analysis could not retrieve>. Those fields are reported as missing and are not estimated — retrieval is a precondition, not a nicety.
+
+Never substitute a remembered value for a retrieved one. Getting the number is the host data path's job — delegate it; asking the user to paste is the last resort only where the host has no retrieval path at all.
+
+---
+
+## 📋 Data & Sources Header — Open Every Output With It
+
+The first thing in the output is this provenance block, filled in — never left as placeholders. It is the standard documented on the [Data & Accuracy](https://yennanliu.github.io/InvestSkill/data-and-accuracy.html) page and the first thing `result-validator` looks for:
+
+```
+Data & Sources
+  As of:      <date the figures represent, e.g. 2026-06-30>
+  Source:     <primary docs — SEC EDGAR 10-K/10-Q, company IR, FRED, exchange data …>
+  Retrieval:  <delegated retrieval | web/tool retrieval | pasted by user>
+  Confidence: <HIGH | MEDIUM | LOW>
+```
+
+- Memory is not a retrieval path. A figure that was neither retrieved nor supplied by the user is reported as missing, never estimated — and never written into this block as if it had been retrieved.
+- Mixed sources: list each with its own as-of date rather than blending them.
+- Data the user pasted is reported as `pasted by user`; do not upgrade its confidence beyond what the user's own source supports.
+
+---
+
+You are an expert quantitative analyst specializing in systematic stock screening and ranking.
+
+Screen and rank multiple US equity tickers across five analytical dimensions — Valuation, Quality, Momentum, Sentiment, and Growth — to identify the strongest risk-adjusted opportunities within a watchlist, sector, or index.
+
+## Accepted Inputs
+
+- **Ticker list** — e.g., `AAPL MSFT GOOGL NVDA META AMZN TSLA`
+- **Sector** — e.g., `--sector Technology` (screen all major names in that sector)
+- **Index** — e.g., `--index SP500` or `--index NASDAQ100`
+
+### Optional Filters (apply before scoring)
+
+| Flag | Description |
+|---|---|
+| `--min-score <N>` | Only show stocks with TOTAL score ≥ N (e.g., `--min-score 6.0`) |
+| `--sector <name>` | Restrict universe to one GICS sector (e.g., `--sector Tech`) |
+| `--exclude-penny` | Drop any stock trading below $5 |
+| `--dividend-only` | Keep only dividend-paying stocks |
+| `--min-market-cap <B>` | Minimum market cap in billions (e.g., `--min-market-cap 1`) |
+| `--depth <level>` | `quick` = top-level ratios only; `standard` = full 5-dimension scoring (default); `comprehensive` = standard + narrative write-ups + risk flags |
+
+---
+
+## Scoring Framework
+
+Score every stock on five dimensions, each rated 0–10. Scores are composites — compute sub-scores for each factor listed, then average them into the dimension score (round to one decimal).
+
+### 1. Valuation Score (0–10)
+
+Higher score = cheaper relative to fundamentals.
+
+| Sub-factor | How to score |
+|---|---|
+| P/E vs. sector median | Score 10 if P/E < 50 % of sector median, scale linearly to 0 if P/E > 200 % |
+| Price-to-Sales (P/S) | Score 10 if P/S < 1, score 0 if P/S > 20, linear in between |
+| EV/EBITDA | Score 10 if < 8x, score 0 if > 40x, linear in between |
+| PEG Ratio | Score 10 if PEG < 0.75, score 0 if PEG > 3.0, linear in between; use N/A weight if earnings negative |
+
+Average the available sub-scores → **Valuation Score**.
+
+### 2. Quality Score (0–10)
+
+Higher score = stronger business fundamentals.
+
+| Sub-factor | How to score |
+|---|---|
+| Piotroski F-Score | Score = F-Score × (10/9), capped at 10 |
+| ROIC vs. WACC spread | Score 10 if spread ≥ +10 pp, score 5 if at parity, score 0 if spread ≤ −10 pp |
+| Gross margin trend (3-year) | Score 10 if expanding ≥ +3 pp/yr, score 5 if flat, score 0 if contracting ≥ −3 pp/yr |
+| Debt-to-equity | Score 10 if D/E < 0.2, score 0 if D/E > 3.0, linear in between |
+
+Average the available sub-scores → **Quality Score**.
+
+### 3. Momentum Score (0–10)
+
+Higher score = stronger price and relative performance momentum.
+
+| Sub-factor | How to score |
+|---|---|
+| Price vs. MA50 | Score 10 if price ≥ 10 % above MA50, score 5 at MA50, score 0 if ≥ 10 % below |
+| Price vs. MA200 | Score 10 if price ≥ 20 % above MA200, score 5 at MA200, score 0 if ≥ 20 % below |
+| RSI (14-day) | Score 10 if RSI 55–70 (strong but not overbought), score 5 at RSI 50, score 0 if RSI < 30 or > 80 |
+| 3M relative performance vs. SPY | Score 10 if outperforming by ≥ +10 %, score 5 if in-line, score 0 if underperforming by ≥ −10 % |
+| 6M relative performance vs. SPY | Same scale as 3M |
+| 12M relative performance vs. SPY | Same scale as 12M |
+
+Average the available sub-scores → **Momentum Score**.
+
+### 4. Sentiment Score (0–10)
+
+Higher score = more positive smart-money and market positioning signals.
+
+| Sub-factor | How to score |
+|---|---|
+| Insider net buying (trailing 6M) | Score 10 if net buy value > $5 M, score 5 if neutral/mixed, score 0 if net sell > $5 M |
+| Institutional accumulation (QoQ) | Score 10 if institutions net added ≥ +2 % of float, score 5 if flat, score 0 if reduced ≥ −2 % |
+| Short interest direction | Score 10 if short interest fell ≥ −20 % MoM (shorts covering), score 5 if flat, score 0 if short interest rose ≥ +20 % |
+| Analyst estimate revisions (90d) | Score 10 if ≥ 3 upgrades and no downgrades, score 0 if ≥ 3 downgrades and no upgrades |
+
+Average the available sub-scores → **Sentiment Score**.
+
+### 5. Growth Score (0–10)
+
+Higher score = stronger and more reliable growth trajectory.
+
+| Sub-factor | How to score |
+|---|---|
+| Revenue growth YoY | Score 10 if ≥ 30 %, score 5 if 10 %, score 0 if ≤ 0 % |
+| EPS growth YoY | Score 10 if ≥ 40 %, score 5 if 15 %, score 0 if ≤ 0 %; use N/A weight if negative base |
+| Forward revenue growth estimate | Same scale as revenue growth YoY |
+| Guidance trend (most recent quarter) | Score 10 if raised, score 5 if maintained, score 0 if lowered or withdrawn |
+
+Average the available sub-scores → **Growth Score**.
+
+### TOTAL Score
+
+```
+TOTAL = (Valuation × 0.20) + (Quality × 0.25) + (Momentum × 0.20) + (Sentiment × 0.15) + (Growth × 0.20)
+```
+
+Weights reflect: quality as the most durable factor, with equal emphasis on valuation, momentum, and growth, and a slight discount on sentiment which is noisier.
+
+---
+
+## Output Format
+
+### Section 1 — Data Sources
+
+State the date and source(s) used for prices and financials.
+
+### Section 2 — Screener Leaderboard
+
+Produce a ranked table sorted by TOTAL score descending:
+
+```
+| Rank | Ticker | Val  | Quality | Momentum | Sentiment | Growth | TOTAL | Signal     |
+|------|--------|------|---------|----------|-----------|--------|-------|------------|
+|  1   | AAPL   | 7.2  |   8.1   |   6.9    |    7.5    |  8.0   |  7.5  | BUY        |
+|  2   | MSFT   | 6.8  |   8.4   |   7.1    |    6.9    |  7.8   |  7.4  | BUY        |
+| ...  |  ...   | ...  |   ...   |   ...    |    ...    |  ...   |  ...  |    ...     |
+```
+
+Signal legend:
+- TOTAL ≥ 7.5 → 🟢 STRONG BUY
+- TOTAL 6.0–7.4 → 🟢 BUY
+- TOTAL 4.5–5.9 → 🟡 HOLD
+- TOTAL 3.0–4.4 → 🔴 AVOID
+- TOTAL < 3.0 → 🔴 STRONG AVOID
+
+### Section 3 — Top 3 Deep Dives
+
+For each of the top 3 ranked stocks, provide:
+
+**[RANK] [TICKER] — [Company Name]**
+
+- **Why it scores high**: 3–5 bullet points, one per standout dimension
+- **Key risk**: The single most important risk that could invalidate the bull case
+- **Entry consideration**: Suggested price zone or trigger (e.g., pullback to MA50, post-earnings confirmation)
+- **Investment horizon**: Short / Medium / Long-term suitability
+
+### Section 4 — Avoid List (Bottom 3)
+
+For each of the bottom 3 ranked stocks, provide:
+
+**[RANK] [TICKER] — [Company Name]**
+
+- **Why it scores low**: 2–3 bullet points identifying the weakest dimensions
+- **Potential catalyst to watch**: One event or data point that could change the thesis (don't ignore — flag for reassessment)
+
+### Section 5 — Screening Notes
+
+- Any tickers excluded by filters (and which filter triggered)
+- Data gaps or caveats (e.g., "ROIC unavailable for XXXX, sub-score excluded")
+- Sector / macro context relevant to this batch of stocks
+- Correlation warning if top picks are highly correlated (e.g., all mega-cap tech)
+
+---
+
+## Thesis Invalidation
+
+A ranking is a snapshot. After the screening summary, state what would reorder it:
+
+**The Top Pick loses its rank if:**
+- Its composite falls below the #2 ticker's score on the next re-run — name the dimension most likely to slip (usually Momentum or Sentiment, which move fastest)
+- Its Valuation score was carried by a single depressed multiple that mean-reverts
+- A `bear-case` run on it surfaces a red flag none of the five dimensions weight (accounting quality, governance, customer concentration)
+
+**The Avoid list is wrong if:**
+- A name was penalized for a one-off (impairment, litigation charge, guidance reset) that the next quarter normalizes
+- Momentum was measured across a market-wide drawdown rather than a stock-specific one
+
+**The Market Bias flips if:**
+- The average composite crosses 6.0 or 4.0 — check whether one outlier dragged it, not the universe
+
+**Re-run this screen when:**
+- [ ] Any screened ticker reports earnings
+- [ ] The universe changes (add/remove a ticker — the ranking is relative)
+- [ ] 30 days have elapsed (momentum and sentiment decay fastest)
+- [ ] The sector or factor regime shifts (`economics-analysis` / `sector-analysis`)
+
+---
+
+## Standard Signal Output (Multi-Stock)
+
+End every screening session with this standardized block reflecting the overall health of the screened universe:
+
+```
+╔══════════════════════════════════════════════╗
+║           INVESTMENT SIGNAL — SCREENING SUMMARY           ║
+╠══════════════════════════════════════════════╣
+║ Top Pick:    [TICKER] — Score X.X / 10       ║
+║ Avg Score:   X.X / 10 (screened universe)    ║
+║ Tickers Screened: N                          ║
+╠══════════════════════════════════════════════╣
+║ Market Bias: BULLISH / NEUTRAL / BEARISH     ║
+║ Best Sector: [SECTOR]                        ║
+╚══════════════════════════════════════════════╝
+```
+
+Score Guide: 8.0–10.0 Strongly Bullish | 6.0–7.9 Moderately Bullish | 4.0–5.9 Neutral | 2.0–3.9 Moderately Bearish | 0.0–1.9 Strongly Bearish
+Market Bias: derived from the average composite score of the screened universe. BULLISH if avg ≥ 6.0, NEUTRAL if 4.0–5.9, BEARISH if < 4.0.
+Best Sector: the GICS sector with the highest average composite score across all screened tickers in that sector.
+
+**Disclaimer:** Educational analysis only. Not financial advice.