parabolic-short-trade-planner

概要

米国株式向けに、Qullamaggie スタイルのパラボリック・ショートのウォッチリストと、条件付きのプレマーケット計画を生成します。このスキルは注文を送信しません。人間がエントリー前にブローカーの情報と照合するための JSON と Markdown を出力します。

3 つのフェーズがあります。

• フェーズ 1（screen_parabolic.py）：FMP から EOD のバーと企業プロフィールを取得し、ハード無効化ルール（モード対応）を適用して、残った銘柄を 5 つの要素（重み 30/25/20/15/10）でスコアリングし、A/B/C/D のグレードを割り当てます。
• フェーズ 2（generate_pre_market_plan.py）：フェーズ 1 の JSON を受け取り、--tradable-min-grade（デフォルトは B）でフィルタリングし、Alpaca の空売り在庫（または ManualBrokerAdapter）を確認し、継承された前日終値に基づいて SEC Rule 201 の SSR 状態を評価し、候補ごとに 3 つのトリガー計画を生成します。
• フェーズ 3（monitor_intraday_trigger.py）：フェーズ 2 の計画を読み込み、5 分足バー（Alpaca のライブデータまたはフィクスチャ）を取得して、各計画の FSM を 1 ステップ進め、計画ごとの状態を永続化し、state、entry_actual、stop_actual、および（トリガー発生時は）shares_actual を含む intraday_monitor JSON を書き込みます。1 回実行型です。トレーダーは watch または cron を使って 1～5 分ごとに実行します。リプレイは決定的で、再実行してもバイト単位で同一の出力になります。

使用する場面

ユーザーが次のことを希望する場合に、このスキルを呼び出します。

• S&P 500（またはカスタム CSV）から日次のパラボリック・ショートのウォッチリストを作成する。
• ウォッチリストを、借株／SSR／状態上限による明示的なゲートを含むプレマーケット取引計画に変換する。
• Alpaca で注文を出す前に、候補をブロックする理由と、手動確認が必要な理由を監査する。

次の場合は呼び出さないでください。

• ロング側のモメンタム・スクリーニング — vcp-screener または canslim-screener を使用してください。
• 1 分足／1 分未満のイントラデイシグナル — フェーズ 3 は 5 分足バーのみを評価します。
• ライブ注文ルーティング — このスキルは設計上、検出のみを行います。フェーズ 3 は具体的なエントリー／ストップ／株数を含む triggered 状態を出力しますが、トレーダーが手動で注文を実行します。

ワークフロー

フェーズ 1 — 日次スクリーナー

1. FMP_API_KEY が設定されていることを確認します（環境変数または --api-key）。
2. デフォルトでより安全なモードを指定して実行します。

   python3 skills/parabolic-short-trade-planner/scripts/screen_parabolic.py \
     --mode safe_largecap --as-of 2026-04-30 --output-dir reports/
   

3. reports/parabolic_short_<date>.md を確認します。ウォッチリストはグレード順（A→D）にまとめられています。
4. 注目する銘柄をフェーズ 2 に進めます。

小型株の急騰後の急落を対象にする場合は、--mode classic_qm に切り替えます（時価総額と ADV の下限が緩和され、5 日間の ROC 閾値が高くなります）。

API を使わずにテストする場合は、--dry-run --fixture <path> を指定して JSON フィクスチャを実行します（scripts/tests/fixtures/dry_run_minimal.json に同梱されています）。

フェーズ 2 — プレマーケット計画ジェネレーター

1. 任意：ライブの借株確認を行うには、ALPACA_API_KEY／ALPACA_SECRET_KEY を設定します。設定しない場合、プランナーは ManualBrokerAdapter にフォールバックし、すべての候補を borrow_inventory_unavailable／plan_status: watch_only として扱います。
2. 実行します。

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

3. 出力：reports/parabolic_short_plan_<date>.json。各計画には 3 つのエントリー計画（5 分足 ORL ブレイク、最初の陰線となる 5 分足、VWAP 失敗）が含まれ、entry_hint／stop_hint の計算式文字列が記載されます（株数はあらかじめ決められていません。トレーダーはトリガー発生時に shares_formula から株数を計算します）。

フェーズ 3 — 日中トリガー監視

1. ALPACA_API_KEY / ALPACA_SECRET_KEY が設定されていることを確認します（フェーズ 3 では Alpaca のマーケットデータを使用します。data.alpaca.markets はペーパー口座とライブ口座の両方で利用できます）。
2. 米国の通常取引時間中、一定間隔で単発実行します。一般的には、最初の 30 分間は 60 秒ごと、その後は 5 分ごとです。

   python3 skills/parabolic-short-trade-planner/scripts/monitor_intraday_trigger.py \
     --plans-json reports/parabolic_short_plan_2026-05-05.json \
     --bars-source alpaca \
     --state-dir state/parabolic_short/ \
     --output-dir reports/
   

   または、watch -n 60 'python3 ...' / cron で実行します。
3. 出力される reports/parabolic_short_intraday_<date>.json には、監視対象の各プランの state（armed / triggered / invalidated / FSM 固有の状態）、バーから算出した状態遷移のタイムスタンプ、およびトリガー時の size_recipe_resolved（具体的な shares_actual）が記載されます。
4. API なしでテストする場合は、JSON フィクスチャ（scripts/tests/fixtures/intraday_bars/）を指定して --bars-source fixture --bars-fixture <path> を使用します。

フェーズ 3 のトリガー検出は、注文の指示ではありません。手動でショートエントリーを行う前に、借株／ロケートの可否、SEC Rule 201 の SSR 状態、ブローカーの空売り制限、およびブローカーが現在適用している日中証拠金またはデイトレードの制限を確認してください。FINRA は、従来のパターンデイトレーダー向け取引日数および最低純資産額 25,000 ドルの要件を日中証拠金基準に置き換えました。この基準は 2026-06-04 に発効し、ブローカーには 2027-10-20 までの段階的な導入が認められています。

フェーズ 3 は冪等です。各実行では、取引開始から now_et（または --now-et による上書き）までの全セッションバーを再処理するため、同じ分の間に再実行しても同じ状態になります。prior_state は差分／通知の表示にのみ使用され、FSM を進めることはありません。

エントリー前のプランの確認

ティッカーごとに、次のトップレベルフィールドを確認します。

• plan_status：actionable（手動ゲートを解除可能）または watch_only（借株不可または SSR 有効などの重大なブロッカー）。
• blocking_manual_reasons：トリガーを引く前に、すべて解消する必要があります。
• advisory_manual_reasons：注意喚起のみです。例：manual_locate_required（常に設定）、warning:too_early_to_short、warning:recent_earnings_catalyst（直近の決算が --earnings-catalyst-window-days 以内にある場合。デフォルトは取引日 10 日間です。この値動きは、純粋なテクニカル要因による急騰ではなく、イベント起因として扱います）。

決算を考慮したスクリーニング

フェーズ 1 は実行ごとに FMP の決算カレンダーを 1 回取得します（銘柄ごとではなく、1 回の呼び出しです）。また、決算を考慮したチェックを 2 つ出力します。

• --exclude-earnings-within-days（デフォルトは今後の暦日 2 日間）— 次回決算がこの期間内にある場合、ハード無効化します。従来の earnings_blackout_days と同じ意味です。
• --earnings-catalyst-window-days（デフォルトは過去の取引日 10 日間）— 前回決算がこの期間内にある場合、ソフト警告 recent_earnings_catalyst を出します。trade_allowed_without_manual: false にはせず、助言的な手動理由としてフェーズ 2 に渡します。

候補ごとの出力には、last_earnings_date、next_earnings_date、trading_days_since_earnings（取引日）、earnings_within_days（今後の暦日）、earnings_blackout_days（設定されたしきい値）、および earnings_in_blackout_window が含まれます。従来の earnings_within_2d も後方互換性のために維持されます。

トップレベルの日付：as_of は計画日です（フェーズ 2 の契約であり、変更しません）。run_date はその日付を反映し、market_data_as_of はテクニカル指標に使用された最新バーの日付です（週末の実行では as_of と異なります）。

取引所カレンダーとリプレイ

プランナーを実行する前に requirements.txt をインストールしてください。フェーズ 1 の --as-of は厳密な YYYY-MM-DD 形式を使用し、それ以降の日付のバーを除外します。また、決算からの経過日数は XNYS の取引日で数えます。フェーズ 3 では、実際の祝日と早引けを考慮し、取引終了時刻は範囲に含みません。過去の日付を指定できるのは、フェーズ 1 の --dry-run でフィクスチャデータを使用する場合のみです。ライブのユニバースおよびプロフィールのエンドポイントは PIT ではないため、現在日以外の --as-of を指定するとフェイルクローズします。

出力形式

フェーズ 1 の JSON：parabolic_short_<as_of>.json（schema_version 1.0）。 フェーズ 2 の JSON：parabolic_short_plan_<as_of>.json（schema_version 1.0）。 フェーズ 3 の JSON：parabolic_short_intraday_<as_of>.json（schema_version 1.0、 phase = intraday_monitor）。 この契約は、フェーズ 3 の tests/test_monitor_intraday_smoke.py と tests/test_schema_contract.py によって固定されています。

リソース

• references/parabolic_short_methodology.md — Qullamaggie の 3 つのトリガーの フレームワークと、勢いの消耗を示すシグナル。
• references/short_invalidation_rules.md — モードに応じた除外ルール。
• references/short_risk_management.md — Rule 201、ETB と HTB、借株の確保。
• references/intraday_trigger_playbook.md — 各トリガーの種類、フェーズ 3 が実装する FSM の 遷移、および同一バーでの判定優先順位の詳細。
• references/broker_capability_matrix.md — 各ブローカーが空売り用の株式在庫について API を通じて提供する情報。