---
name: stockbee-momentum-burst-screener
description: Screen US stocks for Stockbee-style short-term momentum burst setups using 4% breakout, dollar breakout, range expansion, volume expansion, prior range contraction, close-location, failure filters, and risk-distance scoring.
---

# Stockbee Momentum Burst Screener

Screen US equities for Stockbee-style short-term Momentum Burst candidates. The skill is a candidate-generation and setup-quality workflow, not a signal service or an auto-execution system.

## When to Use

- User asks for Stockbee / Pradeep Bonde style Momentum Burst screening
- User wants 4% breakout, dollar breakout, or range expansion candidates
- User asks for short-term 3-5 day swing momentum setups
- User wants to review whether a daily breakout has A/B/C setup quality
- User provides a symbol list, universe file, or historical OHLCV JSON for screening
- User wants candidate outputs to feed into `technical-analyst`, `position-sizer`, or `trader-memory-core`

## Prerequisites

- FMP API key for live universe and historical OHLCV screening:
  ```bash
  export FMP_API_KEY=your_api_key_here
  ```
- Optional no-API path: provide `--prices-json` containing daily OHLCV bars by symbol.
- Run only after the market-regime workflow allows new swing risk, or mark output as manual-review-only.

## Workflow

### Step 1: Choose Input Mode

Use one of three modes:

**Mode A: FMP universe scan**
```bash
python3 skills/stockbee-momentum-burst-screener/scripts/screen_momentum_burst.py \
  --fmp-universe \
  --max-symbols 300 \
  --output-dir reports/
```

**Mode B: Explicit symbols**
```bash
python3 skills/stockbee-momentum-burst-screener/scripts/screen_momentum_burst.py \
  --symbols NVDA SMCI PLTR TSLA \
  --output-dir reports/
```

**Mode C: Offline OHLCV JSON**
```bash
python3 skills/stockbee-momentum-burst-screener/scripts/screen_momentum_burst.py \
  --prices-json data/daily_ohlcv.json \
  --output-dir reports/
```

### Step 2: Run the Screening Pass

The script detects these trigger families:

- **4% Breakout:** `close / previous_close >= 1.04`, volume above previous day, and volume above the liquidity floor
- **Dollar Breakout:** `close - open >= 0.90`, volume above the liquidity floor
- **Range Expansion:** current daily range exceeds the prior three daily ranges while the prior day was not already extended

It then scores setup quality using:

- Trigger strength
- Volume expansion
- Prior base / range contraction quality
- Close location near the high of day
- Risk distance to the trigger-day low
- Failure filters such as prior 3-day run-up or recent 4% breakdown
- Market gate alignment

### Step 3: Review Output

Read the generated JSON and Markdown reports. For each candidate, present:

- Trigger type and all matched trigger tags
- Day gain, dollar gain, volume ratio, and close-location percentage
- Prior base length and base width
- Entry reference, stop reference, and risk percentage to stop
- Setup score, rating, state, and reject reasons
- Suggested downstream action

### Step 4: Send Survivors to Trade Planning

Use the output conservatively:

- **A / A- candidates:** send to `technical-analyst` for manual chart validation, then `position-sizer`
- **B candidates:** watchlist or smaller-risk review only
- **Watch-only candidates:** keep in model book; do not plan a trade unless chart review upgrades the setup
- **Rejected candidates:** retain for post-analysis, not for execution

## Output

- `stockbee_momentum_burst_YYYY-MM-DD_HHMMSS.json` - Structured candidate list, metadata, thresholds, score components, and rejects
- `stockbee_momentum_burst_YYYY-MM-DD_HHMMSS.md` - Human-readable report grouped by rating/state

## Resources

- `references/momentum_burst_methodology.md` - Stockbee-style method summary and implementation boundaries
- `references/scoring_system.md` - Component weights, state thresholds, and failure filters
- `references/entry_exit_rules.md` - Entry reference, stop, sizing handoff, and exit template