allium-investigation

Allium 調査

現在の価格や残高を調べるのではなく、範囲を限定した調査に使用してください。出力は、別の人が検証し、再実行し、異議を唱えられる結論です。

クエリの結果を説明するのではなく、Allium MCP ツール（run_sql_query、get_query_run_results、 create_explorer_query、search_terminal、get_terminal_results、search_schemas、 search_docs）を直接使用してください。MCP が利用できない場合は、 allium-data スキル／CLI に切り替えてください。

出力の要件

まず、意思決定に関する問い、対象、期間、ネットワーク、提案する指標を明記してください。これらのいずれかによって回答が大きく変わる場合は、クエリを実行する前に確認してください。

最後に、回答と、それを直接裏付ける根拠に加え、解釈と未解決の不確実性を明確に示してください。結果を共有、再利用する場合、または意思決定に関わる場合は、チャットの記録に根拠を残すだけで終わらせず、以下のステップ 7 で重要なクエリを Explorer に保存して締めくくってください。

調査ワークフロー

1. 一から調査する前に Terminal を確認する

Allium チームが、すでに回答を作成し、保守している可能性があります。SQL を書く前に、エンティティ／指標／プロトコルを指定して search_terminal を呼び出してください。これはメタデータのみを対象とする検索（ダッシュボードのラベル、パス、カテゴリ、タグ）で、計算コストはかかりません。関連しそうなダッシュボードがあれば、その dashboard_id（chart_id なし）を指定して get_terminal_results を呼び出し、チャートのマニフェストを確認します。次に chart_id を指定して再度呼び出し、SQL や最新の事前計算済み行を取得します。既存の定義と結果を読み取るだけなので、これにも計算ユニットはかかりません。問いに直接答えている場合は、その内容を引用し（事前計算済みの行については result.queried_at を併記）、生テーブルから同じ内容を再導出するのではなく、ダッシュボードにリンクしてください。内容が近いものの完全には一致しない場合も、何もない状態から調査を始めるより速い出発点になるため、最初からやり直すのではなく、その SQL を調整してください。

2. 手法を決める前にデータソースを選ぶ

Terminal ダッシュボードで問いに答えられなかった場合は、次に data-matching を実行してください。データ契約を定義し、候補となるテーブル／エンドポイントと照合したうえで、search_schemas／search_docs を使った範囲限定クエリで網羅性を検証します。テーブル名を推測したり、チェーンが一覧にあるだけで網羅されていると判断したりしないでください。カタログへの登録だけでは網羅性の証明になりません。ソースを選んだら、ネイティブネットワークを特定し、ブリッジされた表現やラップされた表現と区別してから先に進んでください。

3. データ計画を作成する

メインクエリの前に、以下を記録してください。

• 指標の定義と分母
• 対象に含めるもの、除外するもの、エンティティへの帰属ルール
• 時間の粒度とタイムゾーン
• 想定した解釈を反証しうる確認項目

これは仮説として扱ってください。見つかったスキーマや最初の結果が仮説と食い違う場合は、内容を見直してください。

4. 小さなテストから本番用クエリを作成する

対象を絞ったサンプル／カーディナリティ／単位の確認には、run_sql_query を使用します。このツールは明示的に一時的なもので（保存されず、チャートやダッシュボードの元データにもできません）、使い捨ての確認に最適です。すぐに run_id が返るので、その run_id を使って get_query_run_results を呼び出し、ステータス、列、行数、コストを取得します。まだ実行中の場合は、poll_timeout_seconds を指定してください。実行が失敗した場合、エラーになった場合、または行数がゼロだった場合は、SQL を修正して再実行します。空の結果や失敗した実行を回答として報告してはいけません。ただし、質問への答えが実際にゼロ行である場合は除きます。

小さなテストで問題がなく、実際に使うクエリを実行しようとしている段階になったら、最初に run_sql_query で実行するのではなく、create_explorer_query（run_on_creation=True を指定）に切り替えます。検証済みのクエリを run_sql_query で再実行してから保存すると、計算が重複するためです。こうすることで、ステップ 7 に進む時点で、本番用クエリはすでに保存済みの Explorer クエリになっています。

既知のアセットやウォレットの現在の状態には Realtime データを使用します。過去のデータ、比較、集計、チェーンをまたぐ質問には Explorer／SQL を使用します。更新頻度に関する意味合いが異なるこれらのデータを、ラベルなしの単一の指標に混在させてはいけません。

5. 結果を検証する

手法に応じて、以下の確認を行います。

• 合計値とその構成要素を照合します。
• 結合による重複計上がないか確認し、意図した粒度で COUNT(DISTINCT ...) を検証します。
• トークンの単位、小数点以下の桁数、USD 換算、分母を確認します。
• 連続する期間を比較し、断絶があれば平滑化せずに原因を調査します。
• 重要な数値を少なくとも 1 つ、別の集計、フィルター、またはサンプルを使って独立に再クエリします。

外部のアグリゲーターと一致していることを証明として扱ってはいけません。妥当性確認には使えますが、公表する主張には独自の手法と出典の追跡可能性が必要です。

6. 根拠に応じた主張を行う

以下の 3 種類の記述を区別します。

• 観測結果： クエリが直接示す内容です。
• 解釈： あり得る説明です。解釈であることを明記し、裏付けとなる証拠に結び付けます。
• 不明点： 利用可能なデータからは確定できない内容です。

証拠なしに、相関関係を因果関係に、ラベル付きアドレスを確認済みの管理者に、サンプルを母集団全体にすり替えてはいけません。

7. Explorer で再現可能にする

チャットの記録にしか存在しない結論は再現できません。後から確認する人は SQL を記憶から入力し直す必要があります。ステップ 4 の時点で、重要なクエリはすでに create_explorer_query で保存されているはずです。まだ保存されていない場合は、保存されていない run_sql_query の結果のままにせず、今すぐ保存してください。

単一の結果 — 調査で重要なクエリが 1 つだけ得られた場合、通常はそれだけで十分です。必要に応じて、そのクエリに対して create_explorer_visual（チャート／値／テーブルから、データに合った種類を選択）を呼び出し、share_explorer_query でリンクを共有します。このステップの残りは省略してください。

ダッシュボードにまとめる複数の結果 — アプリ内の Allium Assistant はダッシュボードを作成できますが、ダッシュボードモードでは SQL を記述できず、指定された保存済みクエリを組み合わせることしかできません。複数のクエリを直接まとめる MCP ツールはないため、ユーザーが Assistant に貼り付けるプロンプトを作成して引き継ぎます。各クエリを保存した後、次の内容を 1 つ出力します。

Build me a dashboard.

Title: <short title>
Goal: <one sentence — what should this dashboard show?>

Queries:
- <query_id>: <one-line description>. Cols: <col> (stock→last), <col> (flow→sum), ...
- <query_id>: <one-line description>. Cols: ...

Filters: <optional, one line>
Elements: <optional, one line — e.g. "KPI: total_x (last); chart: y over time by chain">

絶対に省略してはいけないのは、クエリ ID と各列の ストック／フローのタグ の 2 つです。ストック指標（供給量、残高、TVL、価格。集計は last／first）を、フロー指標（出来高、件数、手数料。集計は sum）のように合計することは、ダッシュボードで最もよくある実際の不具合です。Assistant は列名だけからこれを推測できません。プロンプトが長くなりそうな場合は、クエリやストック／フローのタグを削る前に、Filters／Elements／Goal を短い語句にまとめてください。全体を 800 文字より十分短く保ち、誰でも一目で確認し、コピーしてそのまま Assistant に貼り付けられる長さにします。