InvestSkill / rules

---
description: Investment analysis rules and frameworks for InvestSkill project
globs: ["**/*.md", "prompts/**", "plugins/**"]
alwaysApply: true
---

# InvestSkill — Cursor Rules & Setup Guide

This is the InvestSkill repository — a collection of 30 professional investment analysis frameworks for US stocks. These rules automatically apply when you work in this project.

## Installation & Setup

### Automatic Setup

Cursor automatically loads this file when you open the InvestSkill repository. **No manual installation required.**

1. **Clone the repository:**
   ```bash
   git clone https://github.com/yennanliu/InvestSkill.git
   ```

2. **Open in Cursor:**
   ```bash
   cd InvestSkill
   cursor .
   ```

3. **Open AI Chat** (usually `Cmd+K`)
   - Cursor automatically loads the investment analysis rules
   - All 30 frameworks are immediately available

### Verify Setup

In Cursor AI Chat, try:
```
@prompts/stock-valuation.md Analyze Apple (AAPL)
```

If the framework loads, setup is complete!

---

## Available Analysis Frameworks (30 frameworks + 3 aliases + 1 output tool)

### Core Stock Analysis (4 frameworks)

| Framework | File | Best For |
|-----------|------|----------|
| Stock Evaluation | `@prompts/stock-eval.md` | Piotroski scoring, quality metrics |
| Stock Valuation | `@prompts/stock-valuation.md` | DCF + comparable companies + EV multiples |
| Technical Analysis | `@prompts/technical-analysis.md` | Chart patterns, volume, indicators |
| Economics Analysis | `@prompts/economics-analysis.md` | Macro indicators, recession probability |

### Financial Report Analysis (3 frameworks)

| Framework | File | Best For |
|-----------|------|----------|
| Financial Report Analyst | `@prompts/financial-report-analyst.md` | 10-K, 10-Q, annual reports |
| 10-K Report Digest | `@prompts/10k-digest.md` | Structured digest doc — abstract, section summaries, metrics, refs (EN/繁中) |
| Earnings Call Analysis | `@prompts/earnings-call-analysis.md` | Management tone, guidance, themes |

### Market Monitoring (4 frameworks)

| Framework | File | Best For |
|-----------|------|----------|
| Insider Trading | `@prompts/insider-trading.md` | Form 4 insider buying/selling |
| Institutional Ownership | `@prompts/institutional-ownership.md` | 13F holdings, smart money moves |
| Dividend Analysis | `@prompts/dividend-analysis.md` | Dividend safety, yield trap detection |
| Short Interest | `@prompts/short-interest.md` | Short squeeze scoring, thesis evaluation |

### Advanced Analysis (14 frameworks)

| Framework | File | Best For |
|-----------|------|----------|
| Competitor Analysis | `@prompts/competitor-analysis.md` | Moat scoring, Porter's Five Forces |
| Industry Map | `@prompts/industry-map.md` | Supply/value-chain graph, chokepoints, value-pool migration |
| Options Analysis | `@prompts/options-analysis.md` | Greeks, IV rank, strategy selection |
| Portfolio Review | `@prompts/portfolio-review.md` | Allocation optimization, performance |
| Sector Analysis | `@prompts/sector-analysis.md` | Sector rotation, opportunity identification |
| Stock Screener | `@prompts/stock-screener.md` | Multi-ticker ranking across valuation, quality, momentum, sentiment, growth |
| Catalyst Calendar | `@prompts/catalyst-calendar.md` | Forward-looking 90-day event calendar, impact scoring |
| Bear Case | `@prompts/bear-case.md` | One-sided short thesis, downside target, counterevidence to a bull thesis |
| Position Ladder | `@prompts/position-ladder.md` | Staged entry ladder, share-count floor/ceiling, trim/re-add cost-basis cycle, wash-sale flags |
| Thesis Tracker | `@prompts/thesis-tracker.md` | Write, save, and re-check an investment thesis — KPIs with thresholds, invalidation triggers, catalysts, a pre-mortem, and a decision log; `--update` re-reads the saved file against new data and returns INTACT / WEAKENED / BROKEN |
| ETF Analysis | `@prompts/etf-analysis.md` | ETF / index-fund due diligence — expense ratio vs. category, tracking difference, liquidity, holdings concentration and tilt, overlap with your other positions, distribution and capital-gains history, structure warnings, and an ETF-vs-top-holdings comparison, scored as an ETF Fitness Score 0–10 |
| Earnings Preview | `@prompts/earnings-preview.md` | The before-earnings skill — consensus vs. whisper, 8-quarter beat rate and post-print move distribution, options-implied vs. realized move, what the current price already assumes, the KPIs to watch, and a three-scenario grid (beat-and-raise / beat-and-lower / miss) with expected reaction and a position rule for each |
| Tax Lens | `@prompts/tax-lens.md` | US tax mechanics for a position or portfolio — short- vs. long-term treatment, wash-sale window check, qualified-dividend holding-period test, lot selection (specific-ID vs. FIFO), tax-loss-harvesting pairs, account placement, estimated annual tax drag — plus a --non-us module (W-8BEN, dividend withholding and treaty rates, capital-gains treatment, US estate-tax exposure, UCITS alternatives). Educational only, never tax advice |
| Risk Stress Test | `@prompts/risk-stress-test.md` | Portfolio and position risk report — beta-weighted exposure, historical scenario replay (2008, March 2020, 2022 rate shock, 2025 tariff shock), parametric VaR / CVaR at 95 / 99 %, max-drawdown estimate, correlation-spike scenario, rate / USD / oil sensitivity, liquidity (days to exit at 20 % of ADV), and a Risk Budget Score 0–10 |

### Full Report (1 frameworks)

| Framework | File | Best For |
|-----------|------|----------|
| Full Report (HTML) | `@prompts/full-report.md` | Runs all modules and saves a standalone HTML report |

### Meta-Analysis & Visualization (5 frameworks)

| Framework | File | Best For |
|-----------|------|----------|
| Result Validator | `@prompts/result-validator.md` | Validate any analysis + confidence score |
| Chart Master | `@prompts/chart-master.md` | Generate Mermaid/ASCII/HTML charts |
| Report Generator | `@prompts/report-generator.md` | Export analysis as a professional HTML/PDF report |
| Learning Coach | `@prompts/learning-coach.md` | Explains any InvestSkill output like a mentor — every metric in plain words, why it matters, its good / bad range, and the lesson that teaches it — then asks 3–5 Socratic questions and "what would change your mind?". --level beginner / intermediate, --lang zh-TW, and a --quiz mode that drills a Learning lesson |
| Fact Check | `@prompts/fact-check.md` | Claim-level verification of any report or data set — extract every figure and factual claim, check each against a primary source (SEC filing, company IR, FRED, exchange data, or the user's own document), recompute derived numbers, mark ✅ verified / ⚠️ mismatch / ❓ unverifiable, and re-issue the report with inline citations and a References section; Verification Score 0–10 |

### Aliases (3 redirects — installed, not counted as frameworks)

These stubs remain so old references keep working; each points at the framework that absorbed it.

| Framework | File | Redirects to |
|-----------|------|--------------|
| Fundamental Analysis | `@prompts/fundamental-analysis.md` | `@prompts/stock-eval.md` |
| DCF Valuation | `@prompts/dcf-valuation.md` | `@prompts/stock-valuation.md` |
| Research Bundle | `@prompts/research-bundle.md` | `@prompts/full-report.md` |


---

## Usage Examples

### Verify a Report Before You Trust It

```text
# Claim-level fact-check with citations — paste the report and its sources
@prompts/fact-check.md [paste the report + the 10-K excerpt / IR release] Verify every number and add sources

# Then score the reasoning
@prompts/result-validator.md [paste the corrected report and the fact-check ledger] Score confidence
```

### Natural Language Queries

Cursor understands the investment context naturally:

```
# Evaluate a stock
Perform a comprehensive stock evaluation of Microsoft

# Get a valuation
What's a fair valuation for Apple using DCF and comparable companies?

# Technical analysis
Analyze Tesla's technical chart setup and key resistance levels

# Financial statement analysis
Deep dive into NVIDIA's balance sheet and cash flow quality

# Economics outlook
Is a recession likely in the next 12 months?

# Combined analysis
Analyze Apple from both fundamental and technical angles
```

### Explicit Framework References

Use `@prompts/` references for precise methodology:

```
# Stock valuation with all methods
@prompts/stock-valuation.md Analyze AAPL using all valuation methods

# Fundamental analysis
@prompts/stock-eval.md Deep dive on Microsoft's fundamentals

# Technical setup
@prompts/technical-analysis.md What are the key chart levels for NVDA?

# Financial reports
@prompts/financial-report-analyst.md Analyze this 10-K filing: [paste text]

# 10-K digest (structured markdown doc, EN or 繁中)
@prompts/10k-digest.md AAPL FY2024 --lang zh-TW

# Earnings transcript
@prompts/earnings-call-analysis.md What's the management tone here? [paste transcript]
```

### With Financial Data

```
# Paste balance sheet
@prompts/stock-eval.md
[paste balance sheet, income statement, cash flow]

# Paste SEC filing for investment analysis
@prompts/financial-report-analyst.md
[paste 10-Q or annual report text]

# Generate structured 10-K digest document
@prompts/10k-digest.md
[paste 10-K sections or specify ticker + fiscal year]

# Paste earnings transcript
@prompts/earnings-call-analysis.md
[paste earnings call transcript]

# Portfolio holdings
@prompts/portfolio-review.md Review my portfolio:
AAPL: 30%
MSFT: 25%
NVDA: 20%
JNJ: 15%
TSLA: 10%
```

### Stock Comparison

```
# Compare valuations
@prompts/stock-valuation.md Compare AAPL vs MSFT valuations

# Compare fundamentals
@prompts/stock-eval.md Compare AAPL and MSFT balance sheets

# Multi-stock analysis
@prompts/full-report.md Analyze AAPL, MSFT, and GOOGL
```

### Specialized Analysis

```
# Dividend safety
@prompts/dividend-analysis.md Is the JNJ dividend safe?

# Short squeeze potential
@prompts/short-interest.md Evaluate short squeeze potential in GME

# Bear case / counterevidence
@prompts/bear-case.md Build the bear case against TSLA and give a downside target

# Position plan for an existing holding
@prompts/position-ladder.md I hold 20 AVGO at $128, now $122 — plan a 60–100 share ladder

# Options strategy
@prompts/options-analysis.md Find bullish options strategies for AAPL earnings

# Competitive moat
@prompts/competitor-analysis.md Does Apple have a defensible moat?

# Insider activity
@prompts/insider-trading.md What are insiders buying at Tesla?

# Smart money tracking
@prompts/institutional-ownership.md Which institutions are buying tech stocks?

# Sector opportunities
@prompts/sector-analysis.md Which sectors should rotate into?
```

### Full Research Report

```
# Complete analysis on one stock
@prompts/full-report.md Provide a comprehensive analysis of Apple (AAPL)

# Quick version
@prompts/full-report.md Quick analysis of Microsoft

# Multi-stock comparison
@prompts/full-report.md Compare AAPL, MSFT, and GOOGL comprehensively
```

### Follow-Up Questions

Cursor remembers context for follow-ups:

```
# Initial analysis
@prompts/stock-valuation.md Build a DCF model for Microsoft

# Natural follow-ups:
What if revenue growth slows to 8%?
How sensitive is the valuation to WACC?
What's the downside case?
What's the margin of safety?
```

---

## Output Format Standards

Every analysis in this workspace follows this structure:

### 1. Executive Summary
- Clear investment thesis
- Primary bullish/bearish drivers
- Time horizon and conviction

### 2. Quantitative Analysis
- **Specific numbers** (not estimates)
- Year-over-year or period comparisons
- Industry/peer benchmarking
- Valuation multiples and metrics

### 3. Qualitative Assessment
- Management quality and capital allocation
- Competitive positioning and economic moat
- Market opportunity and growth drivers
- Risk factors and thesis invalidators

### 4. Standardized Signal Block

All analyses MUST end with this format:

```
╔══════════════════════════════════════════════╗
║              INVESTMENT SIGNAL               ║
╠══════════════════════════════════════════════╣
║ Signal:      BULLISH / NEUTRAL / BEARISH     ║
║ Confidence:  HIGH / MEDIUM / LOW             ║
║ Horizon:     SHORT / MEDIUM / LONG-TERM      ║
║ Score:       X.X / 10                        ║
╠══════════════════════════════════════════════╣
║ Action:      BUY / HOLD / SELL               ║
║ Conviction:  STRONG / MODERATE / WEAK        ║
╚══════════════════════════════════════════════╝
```

---

## File Structure Rules

### When Working on Skills

- **Skill definitions**: `plugins/us-stock-analysis/skills/<skill-name>/SKILL.md`
  - Requires YAML frontmatter with `description` field
  - Used only for Claude Code plugin

- **Universal prompts**: `prompts/<skill-name>.md`
  - Works with Gemini, Copilot, Cursor, and any AI
  - Must match the corresponding SKILL.md
  - NO slash commands or platform-specific syntax

- **Plugin manifest**: `plugins/us-stock-analysis/.claude-plugin/plugin.json`
  - Lists all available skills for Claude Code
  - Update when adding new skills

- **Marketplace config**: `.claude-plugin/marketplace.json`
  - Version and marketplace metadata
  - Update when releasing new versions

### When Adding New Skills

1. **Create skill definition:**
   ```
   plugins/us-stock-analysis/skills/<skill-name>/SKILL.md
   ```
   - Add frontmatter with `description`
   - Write the full prompt framework
   - Include signal block template

2. **Create universal prompt:**
   ```
   prompts/<skill-name>.md
   ```
   - Copy from SKILL.md
   - Remove any platform-specific syntax
   - Ensure it's AI-agnostic

3. **Update manifest files:**
   - Add to `plugins/us-stock-analysis/.claude-plugin/plugin.json` skills array
   - Update `.claude-plugin/marketplace.json` version
   - Update `README.md` skills list and structure

4. **Update documentation:**
   - Add entry to `README.md` (Skills section)
   - Update structure diagram in README
   - Update CHANGELOG.md with new feature

---

## Analysis Quality Standards

Every analysis output in this repository MUST include:

1. **Quantitative Data**
   - Specific numbers (not "around X%" or "approximately")
   - Financial metrics with actual values
   - Valuation multiples with proper context

2. **Comparisons**
   - Year-over-year growth rates
   - Period-over-period trends
   - Industry/peer benchmarking
   - Historical ranges

3. **Context & Benchmarking**
   - How does metric X compare to peers?
   - Is this above or below historical average?
   - What's the industry standard?

4. **Risk Assessment**
   - What could invalidate this thesis?
   - Downside scenarios and triggers
   - Key assumptions and sensitivities

5. **Standardized Signal Block**
   - Always at the end of every analysis
   - Uses consistent format
   - Provides actionable recommendation

---

## Project Structure

```
InvestSkill/
├── .cursor/
│   └── rules/
│       └── invest-skill.mdc      # This file (auto-loaded)
├── .github/
│   └── copilot-instructions.md   # GitHub Copilot integration
├── prompts/                       # 30 frameworks (+ 3 aliases, 1 output tool)
│   ├── stock-eval.md
│   ├── stock-valuation.md
│   ├── fundamental-analysis.md
│   ├── technical-analysis.md
│   ├── dcf-valuation.md
│   ├── economics-analysis.md
│   ├── financial-report-analyst.md
│   ├── 10k-digest.md
│   ├── earnings-call-analysis.md
│   ├── insider-trading.md
│   ├── institutional-ownership.md
│   ├── competitor-analysis.md
│   ├── dividend-analysis.md
│   ├── short-interest.md
│   ├── options-analysis.md
│   ├── portfolio-review.md
│   ├── sector-analysis.md
│   ├── bear-case.md
│   ├── position-ladder.md
│   ├── research-bundle.md
│   ├── result-validator.md
│   ├── chart-master.md
│   ├── thesis-tracker.md
│   ├── etf-analysis.md
│   ├── earnings-preview.md
│   ├── tax-lens.md
│   ├── risk-stress-test.md
│   ├── learning-coach.md
│   ├── fact-check.md
│   └── report-generator.md     # HTML/PDF report design system
├── plugins/
│   └── us-stock-analysis/
│       ├── .claude-plugin/
│       │   └── plugin.json        # Claude Code plugin manifest
│       └── skills/                # Claude Code skills
├── .claude-plugin/
│   └── marketplace.json           # Marketplace config
├── GEMINI.md                      # Gemini CLI setup
├── README.md                      # Complete documentation
└── CHANGELOG.md                   # Version history
```

---

## Tips for Best Results

### 1. Use Framework References
```
# Good: explicit reference
@prompts/stock-valuation.md Analyze AAPL

# Also works: natural language (Cursor applies framework context)
What's a fair valuation for Apple?
```

### 2. Provide Context Data
```
# Better results with specific info
@prompts/stock-valuation.md
Analyze MSFT assuming:
- Revenue growth: 10% CAGR
- WACC: 8.5%
- Terminal growth: 2.5%
- Current price: $450/share
```

### 3. Paste Financial Data
```
# Cursor can analyze pasted data directly
@prompts/stock-eval.md
[paste balance sheet]
[paste income statement]
Analyze liquidity and profitability trends
```

### 4. Chain Multiple Analyses
```
# Comprehensive approach
First: @prompts/stock-eval.md for NVDA quality
Then: @prompts/technical-analysis.md for chart patterns
Finally: @prompts/institutional-ownership.md for positioning
```

### 5. Ask Follow-Ups
```
# Cursor remembers context
@prompts/stock-valuation.md Value MSFT

Then ask:
What's the valuation if growth slows to 8%?
How important is the cloud margin assumption?
What's the bull/bear case range?
```

---

## Cursor-Specific Tips

### Use @-mentions for Files
```
# Reference prompt files directly
@prompts/stock-valuation.md [your query]

# Cursor will load the framework automatically
```

### Paste Documents
```
# You can paste or upload documents
@prompts/financial-report-analyst.md [upload 10-K PDF or paste text]
```

### Use Chat Memory
```
# Cursor remembers your conversation
1. First message: analyze AAPL fundamentals
2. Follow-up: "What about the technical setup?"
3. Cursor remembers it's about AAPL
```

---

## Troubleshooting

### Framework not loading
```
# Make sure file reference is correct:
@prompts/stock-valuation.md (not stock-val or valuation)

# Files are in the prompts/ directory
# Verify the exact filename matches
```

### Want more detailed analysis
```
# Ask Cursor for more depth:
@prompts/stock-eval.md
Analyze AAPL with:
- Detailed cash flow quality metrics
- Working capital trends
- Debt maturity schedule
- Segment margin analysis
```

### Need specific format
```
# Request format changes:
@prompts/stock-eval.md Value MSFT, format as:
1. Executive summary (1 paragraph)
2. Key metrics (table)
3. Quality score with breakdown
4. Bull/bear case
5. Investment signal
```

---

## Additional Resources

- **README.md** — Full setup for Claude Code, Gemini, Copilot, Cursor
- **GEMINI.md** — Detailed Gemini CLI guide
- **.github/copilot-instructions.md** — GitHub Copilot integration guide
- **prompts/** — All 30 framework files (+ 3 aliases, 1 output tool)
- **GitHub Issues** — Report problems or request features

---

## Disclaimer

These analysis frameworks are for **educational purposes only** and do **not** constitute financial advice. Always consult a qualified financial advisor before making investment decisions. Past performance does not guarantee future results.