pp-prediction-goat

Prediction GOAT — Printing Press CLI

前提条件：CLI をインストールする

このスキルは prediction-goat-pp-cli バイナリを使用します。このスキルのコマンドを実行する前に、CLI がインストールされていることを確認してください。インストールされていない場合は、先にインストールします。

1. Printing Press インストーラーでインストールします。

   npx -y @mvanhorn/printing-press-library install prediction-goat --cli-only
   

2. 確認します：prediction-goat-pp-cli --version
3. $GOPATH/bin（または $HOME/go/bin）が $PATH に含まれていることを確認します。

npx によるインストールに失敗した場合（Node がない、オフラインなど）は、Go から直接インストールしてください（Go 1.26.6 以降が必要です）。

go install github.com/mvanhorn/printing-press-library/library/payments/prediction-goat/cmd/prediction-goat-pp-cli@latest

インストール後に --version が「command not found」と表示する場合、インストール時にバイナリが $PATH に追加されていません。確認が成功するまで、このスキルのコマンドを実行しないでください。

設計上、および CI の lint により、読み取り専用です。このバイナリでは構造上、取引できません。topic <name> は、関連する Polymarket と Kalshi のすべての市場／イベント／タグを、約 3 KB のランキング済みバンドルにまとめて返します（公式 Polymarket CLI の約 250 KB の大量データ出力と比べてコンパクトです）。ローカルの SQLite と FTS5 により、一度同期すればクエリは即座に実行でき、費用もかかりません。6 つの画面（trending、resolving、liquid、mispriced、movers、new）で、エージェントやオッズの研究者が毎週行うワークフローをカバーします。

この CLI を使う場面

エージェントが取引をせずに Polymarket と Kalshi の両方の最新の予測市場オッズを必要とするときは、prediction-goat-pp-cli を使ってください。特に便利なコマンドは topic、compare、および 6 つの画面です。それ以外のコマンドはすべて、パワーユーザーが特定の取引所や市場を詳しく調べるためのものです。この CLI は CI による構造上の保証で読み取り専用です。注文の発注、ウォレットの保有、取引への署名ができないため、エージェントのツールチェーンに安全に組み込めます。

独自の機能

この API を使う他のツールにはない機能です。

取引所横断のインテリジェンス

• topic - トピックに関連する Polymarket と Kalshi のすべての市場を、スリムな約 3 KB のランキング済みバンドルで取得します。例：kanye、argentina、chatgpt-5。

  エージェントがあるトピックの最新オッズを必要とする場合、2 つのプラットフォーム用ツールを個別に呼び出して手作業で再ランキングすることなく、両取引所の情報を 1 回の呼び出しで取得できます。

  prediction-goat-pp-cli topic kanye --json
  

• mispriced - Polymarket と Kalshi の暗黙確率がしきい値以上に食い違う、同じ結果を扱う市場を見つけます。

  一方の取引所が誤っている、または一方の側で誤った価格が付けられていることを示す、最も明確なシグナルです。取引ではなく、確率の較正に関する研究に役立ちます。

  prediction-goat-pp-cli mispriced --threshold 0.05 --json
  

• compare - Polymarket と Kalshi で同じトピックの YES／NO と暗黙確率を並べて比較します。

  エージェントやアナリストにとって、「この結果について、どちらの取引所の数値がより有利か、または異なるか」を、1 回の読み取り専用呼び出しで確認できます。

  prediction-goat-pp-cli compare 'arizona basketball' --json
  

• markets diff - 特定の Polymarket 市場と特定の Kalshi 市場を、項目ごとに構造的に比較します。

  すでに 2 つのスラッグ／ティッカーがわかっている場合（たとえば topic <theme> で取得した場合）、両取引所の相違点を diff で正確に確認できます。

  prediction-goat-pp-cli markets diff <pm-slug> <kalshi-ticker> --json
  

探索の手順

• polymarket event-of - 任意の Polymarket 市場スラッグの親イベントのスラッグを検索します。

  スラッグの接尾辞（gamma のフロントエンドは -467、-595 などを付加します）を推測せずに、複数結果のイベント群を確実に特定できます。

  prediction-goat-pp-cli polymarket event-of will-ghana-win-the-2026-fifa-world-cup
  

• polymarket siblings - 既知の市場スラッグの親イベントに属するすべての兄弟市場を一覧表示します。

  1 回の呼び出しで、ワールドカップのイベントにおける全チーム、ドラフトの全指名枠、WCF の全候補を価格とともに取得できます。topic と公開検索のどちらでも見つからない範囲まで調べるのに有効です。

  prediction-goat-pp-cli polymarket siblings will-ghana-win-the-2026-fifa-world-cup --agent
  

• kalshi-series-search - ローカルに同期済みの Kalshi シリーズのティッカーとタイトルを部分一致で検索します。

  探しているものがおおよそわかっている場合、topic より高速で検索漏れも少なくなります（たとえば WEST を検索すると、出来高が $29M のカンファレンス優勝決定シリーズ KXNBAWEST が見つかります）。

  prediction-goat-pp-cli kalshi-series-search WEST --agent
  

画面

• trending - 両方の取引所における24時間の出来高上位銘柄を、順位付きで表示します。

  2つのホームページをスクレイピングせずに、「今日は何に注目すべきか」という問いに、1つのコマンドで答えられます。

  prediction-goat-pp-cli trending --json --limit 20
  

• resolving - 今後1週間／1か月／数日以内に決着する市場を、流動性順に表示します。

  2つのカーソルを再度ページングせずに、「まもなく決着する市場は何か」をエージェントに伝えます。

  prediction-goat-pp-cli resolving --week --json
  

• liquid - 両方の取引所から、正規化された出来高／流動性の下限を上回る市場を表示します。

  100ドルの賭け1つで相場が動くような、流動性の低い市場を除外します。

  prediction-goat-pp-cli liquid --min-volume 100000 --json
  

• movers - 両方の取引所における、24時間または7日間の期間でのインプライド確率の最大変動を表示します。

  ナラティブの変化（価格主導）と、盛り上がりの変化（からの出来高主導）を明らかにします。

  prediction-goat-pp-cli movers --window 7d --json
  

• new - 両方の取引所で過去N日間に作成された市場を表示します。

  新規上場市場には、アルファと誤価格が存在します。

  prediction-goat-pp-cli new --days 7 --json
  

コマンドリファレンス

comments - コメントシステムとユーザーの操作

• prediction-goat-pp-cli comments get-by-id - コメント ID でコメントを取得
• prediction-goat-pp-cli comments get-by-user-address - ユーザーアドレスでコメントを取得
• prediction-goat-pp-cli comments list - コメントの一覧を取得

events - イベント管理とイベント関連の操作

• prediction-goat-pp-cli events get - ID でイベントを取得
• prediction-goat-pp-cli events get-by-slug - スラッグでイベントを取得
• prediction-goat-pp-cli events get-creator - ID でイベントの作成者を取得
• prediction-goat-pp-cli events list - イベントの一覧を取得
• prediction-goat-pp-cli events list-creators - イベントの作成者の一覧を取得
• prediction-goat-pp-cli events list-keyset - カーソルベース（キ​​ーセット）ページネーションを使用してイベントを返し、大規模な結果セットを安定して効率よくページ分割できます。使用...
• prediction-goat-pp-cli events list-pagination - イベントの一覧を取得（ページネーション対応）
• prediction-goat-pp-cli events list-sport-results - スポーツイベントの結果一覧を取得

markets - 市場データと市場関連の操作

• prediction-goat-pp-cli markets get - ID で市場を取得
• prediction-goat-pp-cli markets get-abridged - 情報フィルターで簡略化された市場を検索
• prediction-goat-pp-cli markets get-by-slug - スラッグで市場を取得
• prediction-goat-pp-cli markets get-information - 情報フィルターで市場を検索
• prediction-goat-pp-cli markets list - 市場の一覧を取得
• prediction-goat-pp-cli markets list-keyset - カーソルベース（キーセット）ページネーションを使用して市場を返し、大規模な結果セットを安定して効率よくページ分割できます。使用...

profiles - ユーザープロフィール管理

• prediction-goat-pp-cli profiles <user_address> - ユーザーアドレスで公開プロフィールを取得

public-profile - 公開プロフィールの管理

• prediction-goat-pp-cli public-profile - ウォレットアドレスで公開プロフィールを取得

public-search - 公開検索の管理

• prediction-goat-pp-cli public-search - 市場、イベント、プロフィールを検索

series - シリーズ管理と関連操作

• prediction-goat-pp-cli series get - ID でシリーズを取得
• prediction-goat-pp-cli series list - シリーズの一覧を取得

series-summary - シリーズ概要の管理

• prediction-goat-pp-cli series-summary get-by-id - ID でシリーズ概要を取得
• prediction-goat-pp-cli series-summary get-by-slug - スラッグでシリーズ概要を取得

sports - チームや試合データなど、スポーツ関連のエンドポイント

• prediction-goat-pp-cli sports get-market-types - 有効なスポーツ市場タイプを取得
• prediction-goat-pp-cli sports get-metadata - スポーツのメタデータ情報を取得

status - ステータスの管理

• prediction-goat-pp-cli status - Gamma API のヘルスチェック

tags - タグ管理とタグ関連の操作

• prediction-goat-pp-cli tags get - ID でタグを取得
• prediction-goat-pp-cli tags get-by-slug - スラッグでタグを取得
• prediction-goat-pp-cli tags get-related-by-slug - タグのスラッグで関連タグ（関連性）を取得
• prediction-goat-pp-cli tags get-related-to-atag-by-slug - タグのスラッグに関連するタグを取得
• prediction-goat-pp-cli tags list - タグの一覧を取得

teams - チームの管理

• prediction-goat-pp-cli teams get - ID でチームを取得
• prediction-goat-pp-cli teams list - チームの一覧を取得

適切なコマンドを見つける

やりたいことは分かっていても、どのコマンドを使えばよいか分からない場合は、CLI に直接尋ねてください。

prediction-goat-pp-cli which "<capability in your own words>"

which は自然言語での機能に関する問い合わせを、この CLI の厳選された機能インデックスから最適なコマンドに対応付けます。終了コード 0 は少なくとも 1 件の一致があることを示します。終了コード 2 は確度の高い一致がないことを示します。その場合は --help に切り替えるか、より対象を絞った問い合わせを使用してください。

レシピ

2 つの取引所をまたいで、あるトピックに関するすべての市場を見つける

prediction-goat-pp-cli topic kanye --json --select markets.title,markets.venue,markets.yesProbability,markets.endDate

関連する PM + Kalshi 市場すべてを、ランキング付きの簡潔なバンドルで取得します。--select を使うと各行を 4 つのフィールドに絞れるため、エージェントが受け取るデータ量は大量のデータストリームではなく約 1 KB になります。

今週、決済されるのは？

prediction-goat-pp-cli resolving --week --json --select title,venue,endDate,liquidity --limit 10

両方の取引所を対象に、end_date < now+7d をローカル SQL でフィルタリングし、流動性の降順で並べ替えます。--select により、レスポンスを非常に小さく保てます。

オッズを並べて比較

prediction-goat-pp-cli compare 'arizona basketball' --json

トピックを対応する市場に解決し、各取引所の YES／NO と予測確率を並べて表示します。PM と Kalshi がどこで食い違っているかを正確に示します。

Kalshi のイベント配下にあるすべての子市場を列挙する

イベントティッカーが分かっている場合（多くの場合、kalshi-series-search で検索してから kalshi events list --series で見つけます）、1 回の呼び出しですべての子市場と最新価格を取得できます。

prediction-goat-pp-cli kalshi events get KXMENWORLDCUP-26 --with-markets --agent

上流の /events/{ticker} エンドポイントに with_nested_markets=true を渡します。レスポンスには markets 配列が含まれ、各子市場のティッカー、タイトル、yes_sub_title、ステータス、yes_ask_dollars、no_ask_dollars、volume_24h_fp、expiration_time が含まれます。特定のイベントの子市場だけが必要な場合に、全体を同期する手順に代わる軽量な方法です。

シリーズ配下の Kalshi の全イベントを一覧表示する

prediction-goat-pp-cli kalshi events list --series KXMENWORLDCUP --agent

series_ticker で /events を絞り込みます。ローカルストアはシリーズティッカーでインデックスを作成していないため、--series フラグを指定すると --data-source live が強制されます。イベントティッカーが正確に分からない場合は、kalshi events get --with-markets の前に使用してください。シリーズ → イベント → 市場を 3 回の呼び出しでたどれます。

取引所間の誤った価格設定を見つける

prediction-goat-pp-cli mispriced --threshold 0.05 --json --select pair.pm.title,pair.kalshi.title,delta

予測確率が 5 ポイント以上異なる、同じ結果を対象とする市場ペアを返します。--select で出力を絞り込めます。Kalshi の未取引市場（プラットフォームのデフォルトである 17 セントの売値が付いていて、出来高がゼロの市場）はペアを作成する前に除外されるため、ノイズではなく、対応可能な価格差を確認できます。

イベント Y で X が勝つ確率は？（イベントをたどるレシピ）

1 つの結果の市場スラッグは分かっているものの、同じ複数結果イベントに属する兄弟市場をすべて取得したい場合（例：ワールドカップの全 48 チーム、または NBA ドラフトロッタリーの全 14 指名順）、分かっているスラッグから親イベントをたどり、そこからすべての兄弟市場を取得します。

prediction-goat-pp-cli polymarket siblings will-ghana-win-the-2026-fifa-world-cup --agent

親イベントのメタデータと、yesPercent が設定されたすべての兄弟市場を返します。有名人や複数結果のハブトピックで古くなりがちな上流の /public-search エンドポイントを回避できます。親イベントのスラッグだけが必要な場合は、polymarket event-of <market-slug> と組み合わせてください。

部分文字列で Kalshi のシリーズを検索する

prediction-goat-pp-cli kalshi-series-search WEST --agent

ローカルに同期された kalshi_series の行を対象に、部分文字列で grep します。FTS ランカーで、探しているシリーズティッカー（例：KXNBAWEST）がより高い検索語頻度の一致結果の下位に埋もれてしまう場合に便利です。事前に prediction-goat-pp-cli kalshi sync を実行しておく必要があります。

取引所間の確率を公平に比較する

JSON 出力では、価格が付いたすべての行に yesProbability（0～1 の浮動小数点数。正規の機械処理用フィールド）と yesPercent（表示用に丸めた 0～100 の値）の両方が含まれます。人には常に yesPercent を表示し、計算には yesProbability を使用してください。誤価格設定のペアには、正規の delta に加えて deltaPercent も含まれます。実際の取引がない Kalshi 市場（最終価格なし、出来高なし、スプレッドが広く 1.00 ドルを超えるもの）には untraded: true が付き、テキストモードの YES 列には誤解を招くプラットフォームのデフォルト確率の代わりに untraded と表示されます。

認証の設定

認証は不要です。

prediction-goat-pp-cli doctor を実行して、設定を確認してください。

エージェントモード

任意のコマンドに --agent を追加します。次のオプションに展開されます：--json --compact --no-input --no-color --yes。

• パイプで利用可能 - stdout に JSON を出力し、stderr にエラーを出力します

• フィルタリング可能 - --select でフィールドを絞り込みます。ドット区切りのパスでネストした構造にアクセスでき、配列は要素ごとにたどります。冗長な API でコンテキストを小さく保つために重要です：

  prediction-goat-pp-cli comments list --agent --select id,name,status
  

• プレビュー可能 - --dry-run でリクエストを送信せずに表示します

• オフラインでも利用しやすい - 同期／検索コマンドは、利用可能な場合にローカルの SQLite ストアを使用できます

• 非対話型 - プロンプトは表示されず、すべての入力をフラグで指定します

• 再試行の明示 - 既存の作成を成功として扱う場合に限り、--idempotent を使用してください

レスポンスエンベロープ

ローカルストアまたは API から読み取るコマンドは、出力を出所エンベロープでラップします。

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

データには .results を、ライブデータかローカルデータかの判別には .meta.source を解析してください。人が読める N results (live) の概要は、標準出力がターミナルで、かつ機械可読形式のフラグ（--json、--csv、--compact、--quiet、--plain、--select）が設定されていない場合に限り、標準エラーにのみ出力されます。パイプ経由の利用やエージェントによる利用、明示的に形式を指定した実行では、標準出力に純粋な JSON が出力されます。

自動学習

2 回の呼び出しによるプロトコルです。発見の前に recall を、出力の前に teach & を実行します。CLI はエンティティを認識して照合を検証し、クエリの種類に対応する保存済みプレイブックも提示します。エンベロープを読み、6 分岐の判断ツリーに従ってください。どちらかを省略すると、今後のセッションで得られる無料の想起ヒットを失います。

ステップ 1：発見の前に必ず recall を実行する

新しいユーザーの質問について、topic、compare、polymarket siblings、kalshi events list、その他の発見コマンドを実行する前に、次を実行してください。

prediction-goat-pp-cli recall "<user's question>" --agent

レスポンスエンベロープ：

{
  "query": "...",
  "normalized": "world cup",
  "query_entities": ["England"],
  "found": true | false,
  "match_score": 0.0,
  "results": [
    { "resource_id": "...", "resource_type": "...", "venue": "...",
      "confidence": 2, "entity_match": "exact|partial|unknown",
      "source": "taught|preseed|recipe", "warnings": ["..."] }
  ],
  "mismatches": [ /* only when --debug-mismatches */ ],
  "warnings": [ /* top-level */ ],
  "playbook": {
    "query_family": "...",
    "playbook": {
      "steps": [ { "cmd": "kalshi events get $EVENT --with-markets", "purpose": "..." }, ... ],
      "entity_slots": ["$TEAM", "$EVENT", "$SERIES"],
      "expected_tool_calls": 2
    },
    "slots_resolved": { "$TEAM": { "token": "portugal", "canonical": "Portugal" } },
    "notes": "kalshi events list pages by created_at desc; --series forces --data-source live"
  },
  "notes": "kalshi events list pages by created_at desc; --series forces --data-source live"
}

ステップ 2：6 分岐の判断ツリー

playbook、notes、results[0]、警告の順に確認してください。

if Playbook present:
    -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose)
    -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries
       for the entity slot tokens. If a step's slot is unresolved, fall back to
       discovery for that step only.
    -> Playbook.expected_tool_calls is a budget; if you find yourself running
       materially more, record the divergence via teach-playbook at end-of-session.

elif Notes present (no Playbook):
    -> read Notes verbatim before any discovery step; they carry known gotchas
       for this query family even when no structured choreography exists yet.

elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2:
    -> skip discovery; fetch live prices for Results[*].ResourceID in parallel
       (kalshi markets get <ticker>, markets get-by-slug <pm-slug>, etc.)

elif Found AND Results[0].EntityMatch == "partial":
    -> candidate hint, NOT a hit; read the resource title to validate before trusting

elif (any row in Mismatches[] when --debug-mismatches was passed):
    -> treat as cold start; the stored learning is for a different entity
       (e.g., a "Portugal" learning won't satisfy an "England" query — different canonical)

else:  // Found == false, no playbook, no notes
    -> cold start; run discovery normally; teach the answer afterward AND record
       a playbook + notes via teach-playbook so the next session of the same
       family is faster.

プレイブックとノートは、リソースごとの処理手順とは独立しています。recall のレスポンスには、プレイブックと Results[] のヒットの両方が含まれることがあります。両方を活用してください。プレイブックには実行すべき手順が示され、リソースのヒットがあれば、特定のステップを省略できます。デフォルトでは mismatches を省略してください。コールドスタート時の予期しない動作を調査する場合にのみ、--debug-mismatches を指定してください。

prediction-goat に同梱されている 3 つのプレイブックは、最もよく使われるクエリ形式をカバーしています。odds_for_team（複数の結果があるイベント内で、特定の 1 チームのオッズを取得する）、event_markets（特定の Kalshi イベントまたは Polymarket の親イベントに属するすべての子マーケットを取得する）、series_summary（Kalshi のシリーズヘッダー、開催中のイベント、上位マーケットを取得する）です。それぞれの形式について、実際の利用で見つかった注意点をまとめたノートが付属しています（未取引フラグによるフィルタリング、--series によるライブデータソースの強制、親ティッカーと子ティッカーの判別）。

ステップ 3：必ず warnings を確認する

• parent_event_when_child_exists：親イベントを取得しないでください。警告に推奨される子ティッカーが含まれています。親ティッカーが Results に含まれていても、代わりにその子ティッカーを取得してください。
• low_confidence：行の confidence が 2 未満です。発見を省略する根拠ではなく、ヒントとして扱ってください。
• resource_not_in_store：学習結果が参照するリソースがローカルストアにありません。照合バリデーターがエンティティを分類できなかったため、直接取得して再評価してください。
• cross_alias_match（結果ごと）：行が別名で学習され、entity_lookups を通じてライブクエリの正規名と一致しました（例：「United States」に関する recall に「USA」での学習結果が適用される場合）。resource_id を信頼してください。
• similar_shape_different_entity（トップレベル）：構造が一致する行はありますが、その正規エンティティはライブクエリのものと異なります（例：ユーザーがイングランドについて尋ねたのに、ポルトガルの学習結果がある場合）。コールドスタートとして扱われます。このケースでは、誤解を招く no_learnings_for_query_family 警告の代わりに表示されます。
• ambiguous_alias（トップレベル）：1 つのクエリエンティティが複数の正規名に解決されました（例：「Cards」→ アリゾナ・カージナルスとセントルイス・カージナルス）。ティッカーを決定する前に、曖昧さをユーザーに伝えてください。
• トップレベルの no_learnings_for_query_family：Jaccard のしきい値を超える行がテーブルにありません。完全なコールドスタートです。

ステップ 4：回答を確定した後に teach & を実行する

ティッカー／スラッグを含むユーザー向けの回答を作成した後、それを出力する前に、バックグラウンドで teach の呼び出しを実行します。シェルの & を付けて、呼び出しがすぐに戻り、ユーザー向けの回答をブロックしないようにします。

prediction-goat-pp-cli teach --query "<user's question>" --resource <id1> --resource <id2>

成功時は何も表示されません。最も具体的なリソースを teach してください。探索中に親イベントを取得していても、回答が特定の子ティッカーに関するものなら、子を teach します。そうしないと、CLI は parent_event_when_child_exists の警告を teach.log に記録し、この警告は learnings list --warnings で確認できます。ユーザーに表示されることはありません。CLI は、想起時の別名をまたいだ解決に、シード済みの entity_lookups（ISO 3166 の国コードと、別名を含む NFL／NBA／MLB／MLS のチーム名簿）を使用します。そのため、「Niners」で teach すると、今後の「49ers」のクエリも自動的に満たされます。

ステップ 5：探索に 5 回を超える呼び出しが必要だった場合は、プレイブックを記録する

質問に回答するためにツールを 5 回より多く呼び出し、かつ CLI では明らかにならなかった回避策（暗黙に破棄されるフラグ、未公開のパラメーター、ページネーションの工夫、ペイロードの注意点、取引対象外フラグに関するノイズ）を見つけた場合は、次回、同じクエリファミリーの探索を省けるように、それらを記録します。リソースの学習内容とプレイブックを同じ teach 呼び出しで記録する、統合された 1 回の呼び出し形式を優先してください。

# Common case: record both the resource learning AND the playbook in one call.
prediction-goat-pp-cli teach \
  --query "<user's question>" \
  --resource <id1> \
  --playbook-file ~/playbooks/series-summary.json \
  --playbook-notes-file ~/playbooks/series-summary-notes.md
# (append shell `&` to background it)

# Alternate: playbook-only (no resource ticker to record alongside).
prediction-goat-pp-cli teach-playbook \
  --query "<user's question>" \
  --playbook-file ~/playbooks/series-summary.json \
  --notes-file ~/playbooks/series-summary-notes.md

プレイブックファイルは steps、entity_slots、expected_tool_calls を含む JSON です。ノートファイルは、注意点をそのまま記載した Markdown です。統合された teach 形式では、プレイブックのフラグは任意です。プレイブックを更新または挿入するには、そのうち少なくとも 1 つを設定する必要がありますが、リソースのみの teach として、フラグをすべて省略することもできます。単独の teach-playbook 形式では、--playbook-file と --notes／--notes-file の少なくとも一方を設定する必要があります。両方とも空の場合は拒否されます。プレイブックは、構造上のクエリファミリー（エンティティを除去したもの）をキーにします。そのため、「odds Portugal wins world cup」で学習した手順は、slots_resolved が想起時に実際のクエリの正規化済みエンティティを結び付けることで、England、Brazil、および同じ構造のほかのすべての国に関するクエリにも適用されます。

prediction-goat がプレイブックを同梱している 3 つのファミリー（odds_for_team、event_markets、series_summary）は、よくあるクエリの構造をカバーしています。クエリファミリーにすでにプレイブックがある場合は、全面的に再 teach するよりも、playbook amend（ステップ 6）を優先してください。

今後の想起時にプレイブックが見つかった場合は、それを正解として扱ってください。slots_resolved を使って置き換えながら手順を再実行し、すでに手順として記載されている探索は省略します。また、どの手順を実行する場合も、先に notes を読みます。

Step 6: デバッグ応答で修正点が特定されたら playbook amend & を実行する

デバッグプロトコルへの応答で、ノートやプレイブックに反映すべき具体的な修正点（回避策、未記載のエンドポイント形式、古くなったフィールド名、確認されたスキーマの不一致、空のペイロードに対するフォールバックなど）が特定された場合は、ユーザー向けの応答を出す前に playbook amend を実行してください。teach と同じく、実行後は結果を待たずに進めます。

prediction-goat-pp-cli playbook amend \
  --query "<exact recall query string>" \
  --add-note "<your concrete correction>"
# (append shell `&` to background it)

追記する価値があるのは、今回のセッションで確認し、将来の自分に役立つ挙動です。追記する価値がある例：

• 「kalshi events list --series forces --data-source live を指定する。ローカルストアは series_ticker をインデックス化していない」
• 「有名人関連のハブトピックでは polymarket /public-search が古いままになる。親イベント経由で polymarket の関連イベントにフォールバックする」
• 「取引されていない Kalshi 市場では、出来高ゼロでもプラットフォームのデフォルトの売り気配として 17c が表示される。ペアリング前に untraded: true で除外する」
• 「トピックに対して一方の取引所にしか市場がない場合、compare は構造化されたペアなしの診断結果を返す。これを『データなし』と解釈しない」

ノートに含めるべきではないもの：

• 年ごとの回答（「ポルトガルが優勝する確率は 8%」など）。これは回答であり、学びではありません。
• プレイブックが実行時にすでに取得する、国やチームごとのデータ。
• 既存のノートの内容を言い換えただけの記述。

amend コマンドは、ファミリーの既存のノートにタイムスタンプ付きマーカー（[amend YYYY-MM-DDTHH:MMZ]: <text>）を付けて追記します。amend を複数回実行すると内容が蓄積され、監査証跡を確認できます。そのファミリーにプレイブックがまだない場合、amend はノートのみのプレイブックを作成するため、初回起動時の修正も記録されます。保存済みの内容を確認するには playbook list --agent を使います。

実行例

このプロトコルの元となった 3 つのトレース：

1. 初回：「odds USA wins world cup」 — recall は found=false を返します（まだ学習済みの行がない状態です。事前シードによって作成されている場合もあります）。探索を実行します（kalshi-series-search WORLD、子項目を順に確認）。KXMENWORLDCUP-26-US で回答します。子項目を学習させます：

   prediction-goat-pp-cli recall "odds USA wins world cup" --agent
   # found=false -> discovery
   prediction-goat-pp-cli kalshi-series-search WORLD --agent
   prediction-goat-pp-cli kalshi events get KXMENWORLDCUP-26 --with-markets --agent
   # ...respond with KXMENWORLDCUP-26-US...
   prediction-goat-pp-cli teach --query "odds USA wins world cup" --resource KXMENWORLDCUP-26-US
   # (append shell `&` to background it)
   

2. 学習済み：「odds portugal wins world cup」 — recall は found=true を返し、results[0].entity_match="exact"、results[0].confidence>=2 となります。探索は省略し、ライブ価格を並行して取得します：

   prediction-goat-pp-cli recall "odds portugal wins world cup" --agent
   # found=true, results=[{resource_id: "KXMENWORLDCUP-26-PT", entity_match: "exact"}, ...]
   prediction-goat-pp-cli kalshi markets get KXMENWORLDCUP-26-PT --agent
   

3. 学習済みだが不一致：「odds england wins the world cup」 — ポルトガルの学習内容とエンティティ以外のトークンが共通していても、recall は found=false を返します。エンティティ検証によってポルトガルの行は mismatches に振り分けられています（--debug-mismatches を指定した場合にのみ表示されます）。初回と同様に扱います。レシピエンジンが、シード済みの country_iso2 ルックアップを通じて KXMENWORLDCUP-26-GB を直接解決する場合があります。それ以外は通常どおり探索します。

明示的なテンプレート作成に使う teach-recipe

レシピ推論は、構造が類似した 2 つの teach（ポルトガル＋USA と country_iso2 ルックアップ）からテンプレートを自動抽出します。テンプレートは事前に作成することもできます：

prediction-goat-pp-cli teach-recipe \
  --query-template "odds {entity} wins world cup" \
  --resource-template "KXMENWORLDCUP-26-{entity:country_iso2}" \
  --resource-type kalshi_markets

これは任意です。2 つの teach が蓄積される前にレシピを作成したい場合や、リソーステンプレートで戦略（前方一致検索のための * サフィックス）が必要な場合にのみ使います。

エンティティマッピングの追加に使う teach-lookup

ISO 国コードと主要リーグのスポーツ選手名簿は事前にシードされています。teach-lookup は不足分にのみ使います：

prediction-goat-pp-cli teach-lookup --kind country_iso2 --canonical "Curaçao" --value CW

計算済みの種類（lowercase、uppercase、kebab-case、capitalize-first、slug）は文字列変換で解決されるため、行を追加する必要はありません。

学習を無効にする

• 1 つのコマンドに --no-learn を指定すると、recall と teach の書き込み処理の両方が短絡されます。蓄積された学習内容の影響を受けてはならない、決定論的なエージェントのフローやテストで使います。
• 環境変数に PREDICTION_GOAT_NO_LEARN=true を設定すると、パイプライン全体が無効になります。

過去の teach を監査する

prediction-goat-pp-cli learnings list --agent             # all rows
prediction-goat-pp-cli learnings list --warnings --agent  # rows whose teach raised a warning (parent-vs-child, no-entity-overlap)
prediction-goat-pp-cli forget "<query>" --resource <id>   # undo one teach
prediction-goat-pp-cli forget "<query>" --all             # undo every teach for that query

CLI がフラグを付けたもののブロックしなかった誤った teach を見つけるには、learnings list --warnings を使います。

エージェントからのフィードバック

あなた（またはエージェント）がこの CLI に何か違和感を覚えたら、記録してください。

prediction-goat-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
prediction-goat-pp-cli feedback --stdin < notes.txt
prediction-goat-pp-cli feedback list --json --limit 10

記録はローカルの ~/.prediction-goat-pp-cli/feedback.jsonl に保存されます。PREDICTION_GOAT_FEEDBACK_ENDPOINT が設定され、かつ --send が渡されるか、PREDICTION_GOAT_FEEDBACK_AUTO_SEND=true が設定されていない限り、POST されることはありません。デフォルトではローカルにのみ保存されます。

バグ報告ではなく、意外に感じたことを書いてください。短く、具体的に、1 行で記録します。そこから知見が積み重なります。

出力の配信

すべてのコマンドで --deliver <sink> を指定できます。出力は標準出力に加えて（または標準出力の代わりに）指定したシンクに送られるため、エージェントは手動でパイプ接続せずにコマンド結果を振り分けられます。サポートされるシンクは 3 種類です。

シンク	効果
stdout	デフォルト。標準出力にのみ書き込みます
file:<path>	出力を <path> にアトミックに書き込みます（一時ファイル＋リネーム）
webhook:<url>	出力本文を URL に POST します（--compact の場合は application/json または application/x-ndjson）

不明なスキームは、サポート対象の一覧を示す構造化エラーとともに拒否されます。Webhook の失敗時はゼロ以外の終了コードを返し、URL と HTTP ステータスを stderr に記録します。

名前付きプロファイル

プロファイルは、保存されたフラグ値のセットで、呼び出しごとに再利用できます。スケジュールされたエージェントが毎回同じ設定で同じコマンドを呼び出す場合に使用します。これは HeyGen の「Beacon」パターンです。

prediction-goat-pp-cli profile save briefing --json
prediction-goat-pp-cli --profile briefing comments list
prediction-goat-pp-cli profile list --json
prediction-goat-pp-cli profile show briefing
prediction-goat-pp-cli profile delete briefing --yes

明示的なフラグは常にプロファイルの値より優先され、プロファイルの値はデフォルト値より優先されます。agent-context は、利用可能なすべてのプロファイルを available_profiles に一覧表示するため、情報を参照するエージェントは実行時にプロファイルを検出できます。

終了コード

コード	意味
0	成功
2	使用方法のエラー（引数が誤っています）
3	リソースが見つかりません
5	API エラー（上流側の問題）
7	レート制限中（待ってから再試行してください）
10	設定エラー

引数の解析

$ARGUMENTS を解析します。

1. 空、help、または --help → prediction-goat-pp-cli --help の出力を表示します
2. install で始まる場合 → mcp で終わる場合は MCP のインストール。それ以外の場合は上記の前提条件を参照します
3. その他すべて → 直接使用（--agent を付けて CLI コマンドとして実行します）

MCP サーバーのインストール

この CLI の公開ライブラリ項目またはビルド済みリリースから MCP バイナリをインストールし、登録します。

claude mcp add prediction-goat-pp-mcp -- prediction-goat-pp-mcp

確認：claude mcp list

直接使用

1. インストール済みか確認します：which prediction-goat-pp-cli 見つからない場合は、インストールを提案します（このスキルの先頭にある前提条件を参照）。
2. ユーザーの問い合わせに最適なコマンドを、上記の独自の機能とコマンドリファレンスから選びます。
3. --agent フラグを付けて実行します。

   prediction-goat-pp-cli <command> [subcommand] [args] --agent
   

4. あいまいな場合は、サブコマンドのヘルプを確認します：prediction-goat-pp-cli <command> --help。