Breakout Trade Planner

Generate Minervini-style breakout trade plans from VCP screener output. Calculates entry, stop-loss, and target prices using worst-case risk analysis, with Alpaca-compatible bracket order templates.

No API

Download Skill Package (.skill) View Source on GitHub

Table of Contents

1. Overview

The Breakout Trade Planner sits between the VCP Screener (which finds candidates) and actual order execution (which places trades). It answers the critical question: “I found a VCP setup – now what exactly do I buy, at what price, with how many shares, and where do I set my stop?”

What it solves:

  • Translates VCP screener scores into concrete trade plans with precise entry/stop/target levels
  • Calculates position sizes based on worst-case fill prices (not optimistic signal prices)
  • Enforces portfolio-level risk limits (heat ceiling, sector concentration)
  • Generates two Alpaca bracket order templates per candidate: pre-place (auto-trigger) and post-confirm (5-min candle verification)
  • Classifies candidates into actionable, revalidation, watchlist, rejected, deferred, and constrained – each with clear reasons

Design philosophy (Minervini-aligned):

  • Never chase: maximum 2% above pivot
  • Tight risk: reject any trade with >8% worst-case risk
  • Buy stop-limit orders: trigger at pivot + 0.1%, limit at pivot + 2% to prevent gap chasing
  • Worst-case sizing: all position calculations use the limit price (not the stop price) as entry

Pipeline position:

VCP Screener --> Breakout Trade Planner --> [breakout-monitor (future)]
  (find)           (plan)                     (execute)

2. Prerequisites

No API keys required. This skill works entirely with local VCP screener JSON files.

Required:

  • VCP screener JSON output with schema_version: "1.0" (generated by the VCP Screener skill)
  • Python 3.9+
  • No external skill dependencies (position sizing is built-in)

Optional:

  • --current-exposure-json file for existing portfolio constraints

3. Quick Start 

# Step 1: Run VCP screener first (if not already done)
python3 skills/vcp-screener/scripts/screen_vcp.py --output-dir reports/

# Step 2: Generate trade plans from screener output
python3 skills/breakout-trade-planner/scripts/plan_breakout_trades.py \
  --input reports/vcp_screener_2026-04-12_200418.json \
  --account-size 100000 \
  --risk-pct 0.5 \
  --output-dir reports/

# Or tell Claude:
# "Generate breakout trade plans from the latest VCP screener results
#  with a $100,000 account"

4. How It Works

Trade Price Derivation

From each VCP candidate’s pivot price and last contraction low:

signal_entry = pivot * 1.001     (buy-stop trigger: 0.1% above pivot)
worst_entry  = pivot * 1.02      (buy-limit ceiling: 2% above pivot)
stop_loss    = last_low * 0.99   (1% below last contraction low)

Why two entry prices? A stop-limit order fills anywhere between signal_entry and worst_entry. The planner uses worst_entry for all risk and sizing calculations to ensure plans remain valid even in the worst-case fill scenario.

Minervini Gate

Every candidate passes through a strict gate before receiving a trade plan:

Condition Pre-breakout Breakout
valid_vcp = True Required Required
composite_score >= 70 Required Required
risk_pct_worst <= 8% Required Required
breakout_volume_detected – Required
distance_from_pivot <= 2% – Required
current_price <= worst_entry – Required

Classification

Candidates are sorted by composite score (highest first) and classified:

Classification Criteria Output
Actionable Pre-breakout, passes Gate Order templates + trade plan
Revalidation Breakout, passes Gate Advisory only (no order template)
Watchlist valid_vcp, score 60-69 Pivot alert trigger
Deferred Passes Gate but heat ceiling exceeded Queued for next session
Constrained 0 shares due to sector/position limit Reason documented
Rejected Fails Gate Rejection reason

Position Sizing

Uses the Position Sizer skill internally:

  1. Apply rating-based multiplier to base risk %:
    • Textbook (90+): 1.75x
    • Strong (80-89): 1.0x
    • Good (70-79): 0.75x
  2. Calculate shares from worst_entry and stop_loss
  3. Apply portfolio constraints (max position %, max sector %, heat ceiling)
  4. Track cumulative risk across all generated orders

5. Usage Examples

Example 1: Basic Trade Plan Generation

Prompt:

Generate breakout trade plans from the latest VCP screener results.
Account size: $100,000. Risk 0.5% per trade.

What happens:

  1. Loads the most recent VCP screener JSON
  2. Filters through the Minervini Gate
  3. Calculates position sizes using worst-case entries
  4. Outputs JSON (for automation) and Markdown (for review)

Example 2: With Existing Portfolio Exposure

Create an exposure file:

{
  "sector_exposure": {"Technology": 22.0, "Industrials": 8.5},
  "open_risk_pct": 3.2
}

python3 skills/breakout-trade-planner/scripts/plan_breakout_trades.py \
  --input reports/vcp_screener_2026-04-12.json \
  --account-size 100000 --risk-pct 0.5 \
  --current-exposure-json exposure.json \
  --output-dir reports/

Why useful: Prevents over-concentration. If Technology is already at 22%, adding another Tech stock would be constrained by the 30% sector cap.

Example 3: Conservative Settings 

python3 skills/breakout-trade-planner/scripts/plan_breakout_trades.py \
  --input reports/vcp_screener_2026-04-12.json \
  --account-size 50000 \
  --risk-pct 0.25 \
  --max-portfolio-heat-pct 3.0 \
  --max-chase-pct 1.0 \
  --output-dir reports/

Effect: Smaller positions (0.25% risk), tighter heat ceiling (3%), and only 1% chase tolerance above pivot. Good for volatile markets or smaller accounts.

Example 4: Reading an Actionable Order

A typical actionable order in the JSON output (pivot=$100, last_low=$95):

{
  "symbol": "EXAMPLE",
  "rating_band": "strong",
  "plan_type": "pending_breakout",
  "decision_code": "ACTIONABLE_PREBREAKOUT",
  "trade_plan": {
    "signal_entry": 100.10,
    "worst_entry": 102.00,
    "stop_loss_price": 94.05,
    "risk_pct_worst": 7.79,
    "target_price": 117.90,
    "shares": 62,
    "risk_dollars": 492.90
  },
  "order_templates": {
    "pre_place": {
      "type": "stop_limit",
      "stop_price": 100.10,
      "limit_price": 102.00,
      "order_class": "bracket"
    },
    "post_confirm": {
      "type": "limit",
      "limit_price": 102.00,
      "order_class": "bracket",
      "entry_condition": { "bar_interval": "5min", "..." : "..." }
    }
  }
}

How to read this (pivot=$100, last_low=$95):

  • signal_entry ($100.10): Buy-stop triggers at pivot + 0.1%
  • worst_entry ($102.00): Maximum fill price at pivot + 2%. All sizing uses this
  • stop_loss_price ($94.05): Last contraction low $95 minus 1% buffer
  • risk_pct_worst (7.79%): (102.00 - 94.05) / 102.00 – passes 8% Gate
  • target_price ($117.90): worst_entry + 2R = 102.00 + 2 * (102.00 - 94.05)
  • Two order templates: Choose pre_place (set-and-forget) or post_confirm (wait for 5-min confirmation)

6. Understanding the Output

JSON Report Structure 

breakout_trade_plan_YYYY-MM-DD_HHMMSS.json
├── schema_version: "1.0"
├── parameters           -- All CLI args used
├── input_metadata       -- Source file, candidates count
├── summary              -- Counts and totals
├── actionable_orders[]  -- Trade plans with order templates
├── revalidation[]       -- Breakout-state advisories
├── watchlist[]          -- Developing VCP alerts
├── rejected[]           -- Failed Gate (with reasons)
├── deferred[]           -- Hit portfolio heat ceiling
├── constrained[]        -- Zero shares due to constraints
└── warnings[]           -- Validation issues

Key Fields in Trade Plans

Field Description
risk_pct_signal Risk from signal entry (optimistic)
risk_pct_worst Risk from worst entry (used for Gate)
r_multiples_signal R targets from signal entry (reference)
r_multiples_worst R targets from worst entry (used for orders)
cumulative_risk_pct Running portfolio heat after this order
binding_constraint Which constraint limited the position size

Markdown Report

Human-readable summary with tables for actionable orders, revalidation candidates, and watchlist items.

7. Tips & Best Practices

Risk management:

  • Start with 0.5% risk per trade for accounts under $100K
  • Keep portfolio heat under 6% (default) – this limits total simultaneous risk
  • The --max-chase-pct 2.0 default prevents buying extended breakouts. Tighten to 1.0% in volatile markets

Order template selection:

  • pre_place (stop-limit): Best for busy traders. Place the order before market open, it auto-triggers if price hits the pivot. Risk: may trigger on low-volume fake breakouts
  • post_confirm (limit after 5-min check): Best for active traders with the upcoming breakout-monitor. Waits for close above pivot + volume confirmation on 5-min bars. Lower false-positive rate

When no candidates are actionable:

  • This is normal and expected. The Gate is intentionally strict
  • Check the rejected list to understand why candidates failed
  • Common reasons: risk too high (wide stops), score below 70, invalid VCP pattern, wrong execution state

Combining with other skills:

  • Run VCP Screener with --strict to pre-filter for valid VCPs only
  • Use Position Sizer directly for manual position sizing adjustments
  • Feed actionable symbols to Technical Analyst for chart confirmation

8. Combining with Other Skills

Full Breakout Trading Workflow 

1. VCP Screener          --> Find candidates with VCP patterns
2. Breakout Trade Planner --> Generate trade plans with sizing
3. Technical Analyst      --> Visual chart confirmation
4. [breakout-monitor]     --> 5-min candle execution (future)
5. Trader Memory Core     --> Register thesis, track lifecycle
6. Portfolio Manager      --> Monitor positions via Alpaca

Earnings Momentum Variant 

1. Earnings Trade Analyzer --> Score post-earnings reactions
2. PEAD Screener           --> Find pullback patterns
3. VCP Screener (custom universe) --> Check for VCP on PEAD candidates
4. Breakout Trade Planner  --> Generate entry plans

9. Troubleshooting

“Input JSON missing schema_version”

Your VCP screener JSON was generated before the schema_version field was added. Re-run the VCP screener to generate a new report:

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

All candidates rejected

Check the rejected array in the JSON output. Common causes:

  • “risk_pct_worst > 8%”: Stop-loss is too far from entry. The stock’s last contraction was wide
  • “rating_band=developing”: Score is 60-69 (Good VCP minimum is 70 for orders)
  • “valid_vcp=False”: VCP pattern validation failed (expanding contractions, shallow T1, etc.)
  • “state=Overextended”: Stock is too far above its SMA200 or pivot

Zero actionable in current market

The Minervini Gate is designed to be strict. During market corrections or extended rallies, few stocks may form tight, buyable VCP patterns. This is a feature, not a bug – it keeps you out of low-probability setups.

10. Reference

CLI Parameters

Parameter Default Description
--input (required) VCP screener JSON path
--account-size (required) Account equity ($)
--risk-pct 0.5 Base risk % per trade
--max-position-pct 10.0 Max single position as % of account
--max-sector-pct 30.0 Max sector exposure as % of account
--max-portfolio-heat-pct 6.0 Max total open risk %
--target-r-multiple 2.0 Take-profit R-multiple
--stop-buffer-pct 1.0 % buffer below last contraction low
--max-chase-pct 2.0 Max % above pivot for entry
--pivot-buffer-pct 0.1 % above pivot for buy-stop trigger
--current-exposure-json None Existing portfolio exposure file
--output-dir reports/ Output directory

Rating Bands & Sizing

Band Score Range Sizing Multiplier Action
Textbook 90-100 1.75x base risk Order template generated
Strong 80-89 1.0x base risk Order template generated
Good 70-79 0.75x base risk Order template generated
Developing 60-69 0.0x (no order) Watchlist only
Weak <60 0.0x Rejected

Decision Codes

Code Meaning
ACTIONABLE_PREBREAKOUT Pre-breakout, passes all Gate conditions
REVALIDATION_BREAKOUT Breakout-state, needs live price revalidation

Output Files

File Format Purpose
breakout_trade_plan_*.json JSON Machine-readable plans with order templates
breakout_trade_plan_*.md Markdown Human-readable report for review

Architecture 

plan_breakout_trades.py   Main pipeline: load, gate, size, output
  ├── risk_calculator.py  Trade prices, risk %, R-multiples, sizing (self-contained)
  └── order_builder.py    Alpaca bracket order templates