parabolic-short-trade-planner

Overview

Generate Qullamaggie-style Parabolic Short watchlists and conditional pre-market plans for US equities. The skill never sends orders. It emits JSON + Markdown that a human reviews against their broker before entry.

Three phases:

• Phase 1 (screen_parabolic.py): pulls EOD bars + company profile

from FMP, applies hard invalidation rules (mode-aware), scores survivors on 5 factors (weights 30/25/20/15/10), and assigns A/B/C/D grades.

• Phase 2 (generatepremarket_plan.py): takes the Phase 1 JSON,

filters by --tradable-min-grade (default B), checks Alpaca short inventory (or ManualBrokerAdapter), evaluates SEC Rule 201 SSR state from the inherited prior-day close, and renders three trigger plans per candidate.

• Phase 3 (monitorintradaytrigger.py): reads the Phase 2 plan,

fetches 5-min bars (Alpaca live or fixture), walks each plan's FSM forward by one step, persists per-plan state, and writes an intradaymonitor JSON with state, entryactual, stopactual, and sharesactual (when triggered). One-shot — trader runs it every 1–5 min via watch or cron; replay-deterministic so re-runs are byte-identical.

When to Use

Invoke this skill when the user wants to:

• Build a daily Parabolic Short watchlist from S&P 500 (or a custom CSV).
• Translate a watchlist into pre-market trade plans with explicit

borrow / SSR / state-cap gating.

• Audit a candidate's blocking vs advisory manual-confirmation reasons

before placing an order at Alpaca.

Do NOT invoke for:

• Long-side momentum screening — use vcp-screener or canslim-screener.
• 1-minute / sub-minute intraday signals — Phase 3 evaluates 5-min

bars only.

• Live order routing — this skill is detection-only by design;

Phase 3 emits a triggered state with concrete entry/stop/share count, but the trader fires the order manually.

Workflow

Phase 1 — daily screener

1. Confirm FMPAPIKEY is set (env var or --api-key).
2. Run with the safer-by-default mode:

``bash python3 skills/parabolic-short-trade-planner/scripts/screenparabolic.py \ --mode safelargecap --as-of 2026-04-30 --output-dir reports/ ``

1. Inspect reports/parabolicshort<date>.md — the watchlist is grouped

by grade (A→D).

1. Promote interesting names to Phase 2.

For small-cap blow-offs, switch to --mode classic_qm (looser market cap and ADV floors, higher 5-day ROC threshold).

For testing without the API, run --dry-run --fixture <path> against a JSON fixture (one is shipped at scripts/tests/fixtures/dryrunminimal.json).

Phase 2 — pre-market plan generator

1. Optional: set ALPACAAPIKEY / ALPACASECRETKEY for live borrow

checks. Without them the planner falls back to ManualBrokerAdapter, which marks every candidate as borrowinventoryunavailable / planstatus: watchonly.

1. Run:

``bash python3 skills/parabolic-short-trade-planner/scripts/generatepremarketplan.py \ --candidates-json reports/parabolicshort_2026-04-30.json \ --account-size 100000 --risk-bps 50 --output-dir reports/ ``

1. Output: reports/parabolicshortplan_<date>.json. Each plan contains

three entry plans (5min ORL break, first red 5-min, VWAP fail) with entryhint / stophint formula strings (no baked-in shares — the trader computes shares at trigger time from the shares_formula).

Phase 3 — intraday trigger monitor

1. Confirm ALPACAAPIKEY / ALPACASECRETKEY are set (Phase 3

uses Alpaca market data; data.alpaca.markets works for both paper and live accounts).

1. During US regular session, run one-shot per cadence — typical is

every 60 s during the first 30 min, then every 5 min: ``bash python3 skills/parabolic-short-trade-planner/scripts/monitorintradaytrigger.py \ --plans-json reports/parabolicshortplan2026-05-05.json \ --bars-source alpaca \ --state-dir state/parabolicshort/ \ --output-dir reports/ ` Or wrap in watch -n 60 'python3 ...'` / cron.

1. Output: reports/parabolicshortintraday_<date>.json lists every

monitored plan with state (armed / triggered / invalidated / FSM-specific), bar-derived transition timestamps, and sizereciperesolved (concrete shares_actual) when triggered.

1. For testing without the API, use `--bars-source fixture

--bars-fixture <path> against a JSON fixture (scripts/tests/fixtures/intraday_bars/`).

Phase 3 trigger detection is not an order instruction. Before any manual short entry, confirm borrow/locate availability, SEC Rule 201 SSR state, broker short-sale controls, and the broker's current intraday margin or day-trading controls. FINRA replaced the old pattern-day-trader day-count and $25,000 minimum-equity requirements with intraday margin standards effective 2026-06-04, with broker phase-in allowed through 2027-10-20.

Phase 3 is idempotent: each run replays the full session bars from open up to nowet (or --now-et override), so re-running during the same minute produces the same state. priorstate is used only for diff/notification display; it never advances the FSM.

Reviewing a plan before entry

Read three top-level fields per ticker:

• plan_status: actionable (manual gates can be cleared) or

watch_only (hard blockers — borrow unavailable or SSR active).

• blockingmanualreasons: must all be resolved before pulling the

trigger.

• advisorymanualreasons: heads-up only, e.g.

manuallocaterequired (always set), warning:tooearlytoshort, warning:recentearnings_catalyst (last earnings within --earnings-catalyst-window-days, default 10 trading days — flag the move as event-driven rather than pure technical blow-off).

Earnings-aware screening

Phase 1 fetches the FMP earnings calendar once per run (single call, not per-symbol) and emits two earnings-aware checks:

• --exclude-earnings-within-days (default 2 calendar days, forward) —

hard invalidation when next earnings is within the window. Matches the legacy earningsblackoutdays semantic.

• --earnings-catalyst-window-days (default 10 trading days, backward)

— soft warning recentearningscatalyst when last earnings is within the window. Routes to Phase 2 as an advisory manual reason without forcing tradeallowedwithout_manual: false.

Per-candidate output exposes lastearningsdate, nextearningsdate, tradingdayssinceearnings (TRADING days), earningswithindays (CALENDAR days, forward), earningsblackoutdays (configured threshold), and earningsinblackoutwindow. The legacy earningswithin2d is kept for backward compatibility.

Top-level dates: asof is the planning date (Phase 2 contract — never mutate); rundate mirrors it; marketdataasof is the latest bar date used for technical metrics (differs from asof on weekend runs).

Exchange Calendar and Replay

Install requirements.txt before running the planner. Phase 1 --as-of uses strict YYYY-MM-DD, filters bars beyond that ceiling, and counts earnings age with XNYS sessions. Phase 3 uses actual holidays and early closes; the close boundary is exclusive. Historical dates are accepted only with Phase 1 --dry-run fixture data; live universe and profile endpoints are not PIT and therefore fail closed for a non-current --as-of.

Output Format

Phase 1 JSON: parabolicshort<asof>.json (schemaversion 1.0). Phase 2 JSON: parabolicshortplan<asof>.json (schemaversion 1.0). Phase 3 JSON: parabolicshortintraday<asof>.json (schemaversion 1.0, phase = intradaymonitor). The contract is pinned by tests/testschemacontract.py plus tests/testmonitorintradaysmoke.py for Phase 3.

Resources

• references/parabolicshortmethodology.md — Qullamaggie's 3-trigger

framework and exhaustion signals.

• references/shortinvalidationrules.md — mode-aware exclusion rules.
• references/shortriskmanagement.md — Rule 201, ETB vs HTB, locate.
• references/intradaytriggerplaybook.md — detail on each trigger

type, the FSM transitions Phase 3 implements, and same-bar tie-break semantics.

• references/brokercapabilitymatrix.md — what each broker exposes

through its API for short inventory.