vcp-screener

---
name: vcp-screener
description: Use when the user requests VCP screening, Minervini-style tight-base setups, Stage 2 momentum scanning, or a historical VCP study on one ticker with forward-outcome stats.
category: Screening
version: 1.0.0
tools: []
---

# VCP Screener — Minervini Volatility Contraction Pattern

Identify Stage 2 uptrend stocks forming a Volatility Contraction Pattern (VCP) — Mark Minervini's tight-base setup where a stock corrects in a series of progressively shallower pullbacks on shrinking volume as it approaches a breakout pivot.

## When to Use
- User asks for VCP screening, Minervini-style setups, or tight-base / volatility-contraction candidates
- User wants Stage 2 momentum scanning or breakout candidates with defined risk
- User wants every historical VCP that formed in one ticker's multi-year price history, with forward outcomes

## Data Gathering
Amara has no direct market-data API access, so pull multi-year daily OHLCV and volume history (plus SPY/benchmark history for relative strength) via web_search against a financial data source, or ask the user to paste it. Two data pulls suffice per ticker (the ticker plus the benchmark) — this is not a live cross-sectional scan across hundreds of names unless the user supplies the price data for each candidate.

## The 3-Phase Screening Logic
1. **Pre-Filter** — quote-based screen on price, volume, and 52-week position to cut the universe down.
2. **Trend Template** — a 7-point Stage 2 filter evaluated over roughly 260 days of history (price above rising 150/200-day averages, 200-day MA trending up for ≥1 month, 50-day above 150/200-day, price ≥25% above 52-week low, price within 25% of 52-week high, relative-strength rank generally ≥70). Score against a `trend-min-score` threshold, default 85 out of 100 (raise toward 90+ for a stricter Stage-2 filter).
3. **VCP Detection** — pattern analysis and scoring on names that pass the Trend Template.

## VCP Detection Parameters
- **Contractions**: require at least `min-contractions` pullbacks (default 2, range 2-4 — higher means fewer but higher-quality patterns), each shallower than the last by a `contraction-ratio` (default 0.70, range 0.1-1 — lower means tighter contractions required) and lasting at least `min-contraction-days` (default 5, range 1-30).
- **First correction depth**: `t1-depth-min` (default 10%, range 1-50%) — the first pullback off the high must be at least this deep to filter out shallow noise.
- **Breakout confirmation**: `breakout-volume-ratio` (default 1.5x average volume, range 0.5-10x) — higher requires stronger volume confirmation on the breakout day.
- **Swing sensitivity**: `atr-multiplier` (default 1.5, range 0.5-5) — lower is more sensitive to smaller swings when identifying contraction legs.
- **Lookback window**: `lookback-days` (default 120, range 30-365) — how far back to search for the base.
- **Overextension**: `max-sma200-extension` (default 50%) — distance above the 200-day average beyond which the setup is flagged Overextended and penalized.
- **Wide-and-loose flag**: triggers when the final contraction depth exceeds `wide-and-loose-threshold` (default 15%).
- **Strict mode**: only return names where `valid_vcp=True` and execution state is Pre-breakout or Breakout — Minervini's pure setup definition.

## Historical Single-Ticker Mode
For "find every VCP that ever formed in TICKER," walk the price history with a cursor, re-running detection every `stride-days` (default 5, range 1-60), and attach a forward outcome to each detection: breakout, stop-hit, or timeout, tracked over an `outcome-days` window (default 60, range 5-252) with days-to-outcome, max gain, and max loss. Default scan length is 1260 trading days (~5 years, range 100-5040); e.g. use 750 days (~3 years) with a 90-day outcome window for a shorter, more responsive study, or 2520 days (~10 years) for a long-run pattern census. Deduplicate detections by (first-correction-high date, last-low date, pivot) so the same base isn't re-reported as the cursor ages. Note that market cap and RS percentile in this mode reflect the ticker in isolation, not ranked against a live universe — treat it as pattern study, not portfolio sizing.

## Presenting Results
For each candidate, report: composite score/rating, execution state, pattern type (Textbook VCP / VCP-adjacent / Post-breakout / Extended Leader / Damaged), a note if a state cap downgraded the raw score, contraction depths/ratios (T1/T2/T3), the trade setup (pivot price, stop-loss, risk %), volume dry-up ratio, and relative-strength rank.

**By execution state (primary filter):** Pre-breakout/Breakout = active entry window, size per rating below. Early-post-breakout = underway but above ideal entry — reduce size or wait for a pullback. Extended/Overextended = missed, watchlist only. Damaged/Invalid = do not enter.

**By rating (secondary, once state confirms actionability):** Textbook VCP (90+) — aggressive sizing, 1.5-2x. Strong VCP (80-89) — standard sizing, 1x. Good VCP (70-79) — buy only on volume confirmation above pivot, 0.75x. Developing (60-69) — watchlist, wait for tighter contraction. Weak/No VCP (<60) — monitor or skip.

Always caveat that this is pattern-recognition methodology, not investment advice, and that historical VCP outcomes are not guarantees of future performance.