/vcp-screener

name: vcp-screener
description: Screen S&P 500 stocks for Mark Minervini's Volatility Contraction Pattern (VCP) and detect historical VCPs in a single ticker's price path. Identifies Stage 2 uptrend stocks forming tight bases with contracting volatility near breakout pivot points; in historical single-ticker mode walks a multi-year history and emits every VCP that formed with forward-outcome stats (breakout / stop-hit / timeout). Use when user requests VCP screening, Minervini-style setups, tight base patterns, volatility contraction breakout candidates, Stage 2 momentum stock scanning, or historical VCP pattern study on a specific ticker (e.g. FIX, TSLA).

VCP Screener - Minervini Volatility Contraction Pattern

Screen S&P 500 stocks for Mark Minervini's Volatility Contraction Pattern (VCP), identifying Stage 2 uptrend stocks with contracting volatility near breakout pivot points.

When to Use

• User asks for VCP screening or Minervini-style setups
• User wants to find tight base / volatility contraction patterns
• User requests Stage 2 momentum stock scanning
• User asks for breakout candidates with defined risk
• User asks "find every historical VCP in <TICKER>" or wants to study one ticker's

past VCP setups with forward outcomes (`--history --ticker SYM`)

Prerequisites

• FMP API key (set `FMP_API_KEY` environment variable or pass `--api-key`)
• Free tier (250 calls/day) is sufficient for default screening (top 100 candidates)
• Paid tier recommended for full S&P 500 screening (`--full-sp500`)

Workflow

Step 1: Prepare and Execute Screening

Run the VCP screener script:

# Default: S&P 500, top 100 candidates
python3 skills/vcp-screener/scripts/screen_vcp.py --output-dir skills/vcp-screener/scripts

# Custom universe
python3 skills/vcp-screener/scripts/screen_vcp.py --universe AAPL NVDA MSFT AMZN META --output-dir skills/vcp-screener/scripts

# Full S&P 500 (paid API tier)
python3 skills/vcp-screener/scripts/screen_vcp.py --full-sp500 --output-dir skills/vcp-screener/scripts

Strict Mode (Minervini pure setup)

Only return stocks with `valid_vcp=True` AND `execution_state` in `(Pre-breakout, Breakout)`:

python3 skills/vcp-screener/scripts/screen_vcp.py --strict --output-dir reports/

Historical single-ticker mode

Walk one ticker's multi-year history, detect every VCP that ever formed, and attach forward-outcome stats (breakout / stop-hit / timeout, days-to-outcome, max gain, max loss) per detection. Useful for pattern study and backtesting context — not a real-time screener.

# Default: scan ~5 years (1260 trading days), 5-day stride, 60-day outcome window
python3 skills/vcp-screener/scripts/screen_vcp.py \
  --history --ticker FIX --output-dir reports/

# Custom scan length: 750 trading days (~3 years), 90-day outcome window
python3 skills/vcp-screener/scripts/screen_vcp.py \
  --history 750 --ticker TSLA \
  --stride-days 5 --outcome-days 90 \
  --output-dir reports/

# Long scan: 10 years (2520 trading days)
python3 skills/vcp-screener/scripts/screen_vcp.py \
  --history 2520 --ticker NVDA --output-dir reports/

Outputs (timestamped):

• `vcp_history_<SYM>_<YYYY-MM-DD_HHMMSS>.json` — timeline of detections with full

analyzer payload + `forward_outcome` per detection + summary stats.

• `vcp_history_<SYM>_<YYYY-MM-DD_HHMMSS>.md` — human-readable timeline.

Mode-specific flags:

| Parameter | Default | Range | Effect | |-----------|---------|-------|--------| | `--history [DAYS]` | (off) / 1260 if bare | 100-5040 | Enable historical mode; optionally specify trading-day scan window (requires `--ticker`) | | `--ticker SYM` | — | — | Ticker to scan | | `--stride-days` | 5 | 1-60 | Trading-day step between as-of cursor positions | | `--outcome-days` | 60 | 5-252 | Forward window evaluated per detection |

Notes:

• Two FMP API calls per scan (ticker + SPY history), not 100+ like the

cross-sectional pipeline.

• `marketCap` and absolute RS percentile reflect the ticker in isolation,

not against the live screening universe — use this report for pattern study, not portfolio sizing.

• Detections are deduplicated by `(T1_high_date, last_low_date, pivot)` so

the same VCP isn't reported repeatedly as the cursor ages.

Advanced Tuning (for backtesting)

Adjust VCP detection parameters for research and backtesting:

python3 skills/vcp-screener/scripts/screen_vcp.py \
  --min-contractions 3 \
  --t1-depth-min 12.0 \
  --breakout-volume-ratio 2.0 \
  --trend-min-score 90 \
  --atr-multiplier 1.5 \
  --output-dir reports/

| Parameter | Default | Range | Effect | |-----------|---------|-------|--------| | `--min-contractions` | 2 | 2-4 | Higher = fewer but higher-quality patterns | | `--t1-depth-min` | 10.0% | 1-50 | Higher = excludes shallow first corrections | | `--breakout-volume-ratio` | 1.5x | 0.5-10 | Higher = stricter volume confirmation | | `--trend-min-score` | 85 | 0-100 | Higher = stricter Stage 2 filter | | `--atr-multiplier` | 1.5 | 0.5-5 | Lower = more sensitive swing detection | | `--contraction-ratio` | 0.70 | 0.1-1 | Lower = requires tighter contractions | | `--min-contraction-days` | 5 | 1-30 | Higher = longer minimum contraction | | `--lookback-days` | 120 | 30-365 | Longer = finds older patterns | | `--max-sma200-extension` | 50.0% | — | SMA200 distance threshold for Overextended state and penalty | | `--wide-and-loose-threshold` | 15.0% | — | Final contraction depth above which wide-and-loose flag triggers | | `--strict` | off | — | Minervini strict mode: only Pre-breakout or Breakout with valid VCP |

Step 2: Review Results

1. Read the generated JSON and Markdown reports 2. Load `references/vcp_methodology.md` for pattern interpretation context 3. Load `references/scoring_system.md` for score threshold guidance

Step 3: Present Analysis

For each top candidate, present:

• **Quality** (`composite_score` / rating) — how well-formed is the VCP pattern?
• **Execution State** (`