cot-contrarian-detector

COT Contrarian Detector

Overview

Implements step 1 of Jason Shapiro's COT (Commitment of Traders) contrarian process: detect when large speculators are crowded into one side of a futures market. Crowded positioning is a precondition for a contrarian trade, not a trade signal — a market only becomes tradable once crowding is confirmed by a news failure and price-action reversal (steps 2-3), which this skill guides the user through manually.

Core thesis (Shapiro): Large speculators (hedge funds, CTAs, momentum traders) tend to be maximally positioned at trend exhaustion, not trend inception. When they are already crowded onto one side, the next big move is statistically more likely to run them over than to reward them further. Fade the speculators, not the commercials (commercials hedge for structural reasons and are not a crowd-psychology signal).

When to Use This Skill

English:

• "What markets are the speculators crowded into right now?"
• "Run a COT report analysis" / "Show me COT positioning extremes"
• "Is anyone 'trapped' in gold / the dollar / bonds right now?"
• User wants to find contrarian futures setups
• User asks for a Jason Shapiro-style COT screen

Japanese:

• 「COTレポートで買われすぎ・売られすぎのポジションを調べて」
• 「投機筋が偏っている市場は？」
• 「ジェイソン・シャピロ式の逆張り分析をして」

Do NOT use when:

• The user wants a trade signal right now — crowding alone is not actionable; see Guardrails below
• The user is asking about individual equities — COT reports cover CFTC futures markets only (indices, rates, FX, metals, energy, agri, crypto), not single stocks

Prerequisites

• FMP API Key: Required. Set FMP_API_KEY environment variable or pass --api-key. COT endpoints require an FMP Premium+ plan — a free-tier key will not have access.
• Python 3.9+ with requests installed.
• API Budget: One call per market (23 for --core, up to ~65 for the full universe), plus one call for the market list when neither --symbols nor --core is given.

Workflow

Phase 1: Run the crowding screen

# Curated core futures universe (23 liquid/representative markets)
python3 skills/cot-contrarian-detector/scripts/screen_cot_crowding.py --core --output-dir reports/

# Explicit symbols
python3 skills/cot-contrarian-detector/scripts/screen_cot_crowding.py --symbols "ES,GC,CL" --output-dir reports/

# Full universe (all ~65 markets FMP's COT list covers)
python3 skills/cot-contrarian-detector/scripts/screen_cot_crowding.py --output-dir reports/

The script fetches each market's weekly legacy COT report (large-speculator long/short positions), computes a 156-week (3-year) and 26-week COT Index per market, and classifies extremes:

• CROWDED_LONG — COT Index >= 90 (near the 3-year net-long high)
• CROWDED_SHORT — COT Index <= 10 (near the 3-year net-short high)
• NEUTRAL — everything in between

Markets with insufficient history to compute the index are never silently dropped — they appear in a skipped list with the reason (e.g. "insufficient history: 40/156 weeks").

Phase 2: Present the crowding report

Present the generated Markdown report, highlighting:

• Which markets are CROWDED_LONG / CROWDED_SHORT and by how much
• The 26-week index for context (is the crowding fresh or aging?)
• Week-over-week net-position swings (fast-moving crowds are more fragile)
• The methodology note and disclaimer — crowding is not a trade signal

フェーズ 3：手順 2～5 を手動でガイドする（Shapiro のプロセス）

ユーザーが CROWDED_LONG ／ CROWDED_SHORT の市場で取引を検討する場合は、 references/shapiro-methodology.md を読み込み、残りの手順を進めてください。 これらの手順は自動化されていません。

1. 群集度の検出（完了 — このスキル）
2. ニュースの失敗 — WebSearch を使って、群集の方向にとって好材料となる最近のニュースが、群集の予想どおりに価格を動かせなかったかを確認します （例：買いに大きく傾いた市場が、強気のニュースを受けても上昇しない）。これが中核的な優位性であり、最も重要な手動確認です。
3. 値動きの確認 — 週足チャートで反転パターン、または新高値／新安値を更新できなかった形跡を確認します。
4. エントリー — 群集と逆方向に、直近のスイングの極値にストップを置き、固定リスクで小さくポジションを取ります（position-sizer スキルを参照）。
5. エグジット — ポジショニングが中立方向へ正常化したとき（COT Index が 50 に戻る方向へ動いたとき）、またはストップに達したとき。

群集度だけを根拠にエントリーを推奨してはいけません。手順 2 と 3 の両方で確認が取れてからにしてください。

出力

• JSON： reports/cot_crowding_<as-of-date>.json — 機械可読形式です。run_context ブロック（schema_version、params、universe、data_date）に加えて、markets（順位付けされた結果）と skipped（除外した市場。黙って除外しない）を含みます。
• Markdown： reports/cot_crowding_<as-of-date>.md — 人が読みやすいレポートです。Crowded Long ／ Crowded Short ／ Full Ranking ／ Week-over-Week Swings ／ Skipped Markets ／ Methodology の各セクションが含まれます。

実行頻度

CFTC は COT レポートを金曜日の午後 3 時 30 分頃（ET）に公開します。ポジションの基準日は直前の火曜日です。そのため、公開時点ですでにデータは 3 日以上古く、次の金曜日には最大 9 日前のデータになります。このスキルは次のタイミングで実行してください。

• 毎週： 金曜日の公開後または週末に、最新の状況を確認するため
• 随時： ユーザーが特定市場のポジショニングについて尋ねたとき — いずれの場合も、基になるデータは直近の金曜日に公開されたものです

ガードレール

• 群集度だけでは取引シグナルになりません。 あくまで前提条件です。references/shapiro-methodology.md の手順 2（ニュースの失敗）と手順 3（値動き）でも確認が取れない限り、エントリーを提案してはいけません。
• データには遅れがあります。 COT ポジションは、参照する時点で 3～9 日前のものです。リアルタイムのシグナルとして扱わないでください。
• コマーシャルではなく、投機筋を逆張りの対象にします。 このスキルが参照するのは非商業筋（「大口投機筋」）のポジショニングのみです。商業筋のヘッジフローは構造的に異なるため、群集心理のシグナルにはなりません。
• 投資助言ではありません。 すべての出力は調査・教育目的です。

リソース

references/shapiro-methodology.md

5 段階の全プロセス（群集度 → ニュースの失敗 → 値動き → エントリー → エグジット）、コマーシャルではなく投機筋を逆張りの対象とする理由、公開までの 3 日間の遅延に関する注意点、このスキルで自動化される項目と手動のままの項目を示す表が記載されています。ユーザーを手順 1 の先へ導くときは、必ずこのファイルを読み込んでください。

references/cot-index-calculation.md

COT Index の計算式、ルックバック期間の根拠（主期間は 156 週／文脈確認用は 26 週）、極値のしきい値の感度、建玉による正規化の根拠、旧式レポートと細分化レポートの違い（このスキルでは旧式レポートの非商業筋＝大口投機筋のフィールドを使用）、および scripts/cot_index.py が使用する FMP COT API のフィールド名一覧が記載されています。

同梱クライアント：scripts/fmp_client.py（生成済み）が FMP との通信処理を担当します。レート制限、429 時の 1 回の再試行、ヘッダー認証（キーは URL に表示されません）、(data, error) の結果に含まれる apikey のマスキングを処理します（Issue #495）。

参照資料を読み込むタイミング

• 初回使用時／方法論の説明時： references/shapiro-methodology.md を読み込みます
• レポート内の特定の数値の説明時： references/cot-index-calculation.md を読み込みます
• 定期実行時： 参照資料は不要です — スクリプトが群集度を計算します