allium-investigation

Files (1)

• SKILL.md

SKILL.md (first lines)

# Allium Investigation

Use this for a scoped investigation, not for a current price or balance lookup. Its output
is a conclusion that another person can inspect, rerun, and challenge.

Use the Allium MCP tools directly — `run_sql_query`, `get_query_run_results`,
`create_explorer_query`, `search_terminal`, `get_terminal_results`, `search_schemas`,
`search_docs` — rather than describing what a query would show. If the MCP isn't
available, fall back to the `allium-data` skill / CLI.

## Output contract

Start by stating the decision question, subject, time window, networks, and proposed
metric. If any of these would materially change the answer, ask before querying.

End with the answer and the evidence that directly supports it, plus clearly marked
interpretation and open uncertainty. If the result will be shared, reused, or is
decision-relevant, finish with step 7 below — saving the load-bearing queries to Explorer
— rather than leaving the evidence only in the chat transcript.

## Investigation workflow

### 1. Check Terminal before investigating from scratch

Someone on the Allium team may have already built and maintained the answer. Call
`search_terminal` with the entity/metric/protocol before writing any SQL — it's a
metadata-only search (dashboard label, path, category, tags), no compute cost. If a
dashboard looks relevant, call `get_terminal_results` with its `dashboard_id` (no
`chart_id`) to see the chart manifest, then again with a `chart_id` to pull its SQL
and/or latest precomputed rows — this also costs no compute units, since it only reads
existing definitions and results. If it directly answers the question, cite it (with
`result.queried_at` for the precomputed rows) and link the dashboard instead of
re-deriving the same thing from raw tables. If it's close but not exact, it's still a
faster starting point than a blank investigation — adapt its SQL rather than starting
over.

### 2. Select the source before committing to a method

Run `data-matching` next if a Terminal dashboard didn't already answer the question — it
defines the data contract, compares candidate tables/endpoints against it, and proves
coverage with a bounded query via `search_schemas`/`search_docs`. Don't guess a table name
or infer coverage from a chain merely being listed; a catalog entry alone is not coverage.
Once a source is selected, identify the native network and distinguish it from bridged or
wrapped representations before proceeding.

### 3. Write a data plan

Before the main query, record:

- the metric definition and denominator;
- inclusion, exclusion, and entity-attribution rules;
- time grain and timezone;
- the checks that could falsify the intended interpretation.

Treat this as a hypothesis. Revise it when the discovered schema or first result disagrees.

### 4. Build from a small test to a production query

For the narrow-sample/cardinality/units check, use `run_sql_query` — it's explicitly
ephemeral (not saved, can't back a chart or dashboard), which is exactly right for a
throwaway check. It returns a `run_id` immediately; call `get_query_run_results` with that
`run_id` to get status, columns, row count, and cost (pass `poll_timeout_seconds` if it's
still running). If the run failed, errored, or came back with zero rows, fix the SQL and
re-run — don't report an empty or failed run as the answer unless zero rows genuinely *is*
the answer to the question asked.

Once the small test looks right and you're about to run the query whose result you'll
actually use, switch to `create_explorer_query` (with `run_on_creation=True`) instead of
running it through `run_sql_query` first — re-running an already-validated query through
`run_sql_query` and saving it afterward duplicates the compute. This also means the
production query is already a saved Explorer query by the time you reach step 7.

Use Realtime data for current state of a known asset or wallet. Use Explorer/SQL for
historical, comparative, aggregated, or cross-chain questions. Do not mix their freshness
semantics into one unlabeled metric.

### 5. Validate the result

Apply the checks that fit the method:

- reconcile a total with its components;
- check joins for duplicate multiplication and verify `COUNT(DISTINCT ...)` at the
  intended grain;
- confirm token units, decimals, USD conversions, and the denominator;
- compare adjacent periods and investigate discontinuities rather than smoothing them;
- independently re-query at least one load-bearing figure from a different aggregation,
  filter, or sample.

Do not treat agreement with an external aggregator as proof. It can be a sanity check, but
the published claim needs its own method and source trail.

### 6. Make calibrated claims

Separate three kinds of statements:

- **Observed:** what the query directly shows.
- **Interpretation:** a plausible explanation, labelled as such and tied to supporting
  evidence.
- **Unknown:** what the available data cannot establish.

Do not turn correlation into causation, a labelled address into a verified controller, or
a sample into a population without evidence.

### 7. Make it reproducible in Explorer

A conclusion that only exists in the chat transcript isn't reproducible — anyone revisiting
it has to retype the SQL from memory. By step 4 your load-bearing query should already be
saved via `create_explorer_query`; if it isn't yet, save it now rather than leaving it as
an unsaved `run_sql_query` result.

**Single result** — if the investigation produced one load-bearing query, that's usually
enough on its own: optionally call `create_explorer_visual` on it (chart/value/table — pick
the type that fits the data) and, if `share_explorer_query` is available, call it to hand back a link. Skip the rest
of this step.

**Multiple results meant to become a dashboard** — the Allium Assistant in the app builds
dashboards, but it cannot write SQL in dashboard mode; it only assembles saved queries it's
told about. There's no MCP tool to assemble a multi-query dashboard directly, so the
hand-off is a prompt the user pastes into Assistant. After saving each query, print one:

From allium-labs/allium-claude-plugin, MIT.

More from allium-labs/allium-claude-plugin