/dashboard

name: dashboard
description: "Load when the user asks for a dashboard. Covers the dashboard JSON file, SQL datasets, chart types, and the two check tools."
type: skill

Dashboard

A dashboard is one file: `artifacts/<name>.dashboard.json`. You write the file. The chat renders it as an interactive dashboard. The exact contract is `dashboard.schema.json` in this skill directory. Read it when a check tool reports a schema error.

The renderer does not aggregate, join, or compute. It reads rows from the datasets you name, applies filter defaults, the chart `sort`, and the chart `limit`, then draws. Aggregate the data in SQL before you write the file.

Datasets

Every dataset comes from one SQL query. The query defines the dataset. The rows the dashboard shows are only the cached result of that query.

• Put all derivations in the SQL. Use window functions for trailing sums and

year-over-year change. Use `CASE` for groupings such as region. Use CTEs for shares and ranks.

• Do not transform rows in pandas. A dataset that is shaped outside SQL

cannot be refreshed, and the check tools report it as stale.

• Call `sp.dashboard_dataset("monthly", connection="warehouse", sql="...")`

once per dataset in the notebook. It runs the query on the governed path, writes the snapshot at `artifacts/datasets/monthly.csv`, records the SQL that produced it, and returns a DataFrame you can inspect.

• Copy the same connection and SQL into the dashboard file. The check tools

compare the file against the record. A different SQL or connection is `snapshot_stale`.

• Use `rows` only for constants that never change. Inline `rows` hold at

most 5000 flat objects.

• Never write `artifacts/datasets/*.csv` by hand.

Reuse datasets

Several charts can read different columns of one dataset when the grain matches. One query with one row per region can feed a bar chart, a pie chart, a table, and a combo chart. Build the KPI row from one query that returns one row with one column per tile. Do not write one query per chart when one wide query serves them.

Put `TOP` or `LIMIT` in the SQL when the snapshot must be small. The chart `limit` is presentation only. The snapshot keeps every row the SQL returned.

Workflow

Load the skill `signalpilot-dbt:notebook` first. It explains the notebook tools and the `sp` SDK that the steps below use.

1. Write one SQL query per dataset. Aggregate to the grain the chart shows: one row per bar, per point, per pie slice, or per table row. Run `sp.dashboard_dataset(name, connection=..., sql=...)` for each. Read the returned DataFrame and fix the SQL until the columns and rows are right. 2. Write `artifacts/<name>.dashboard.json` with the same connection and SQL in `datasets`. Give every chart a stable `id` that matches `^[a-z][a-z0-9_]{0,63}$`. Keep the same ids when you change the file later. 3. Call `dashboard_sample_data` with the path and all chart ids. Read the `issues` of every chart. Fix each issue in the file or in the SQL. After a SQL change, call `sp.dashboard_dataset` again and copy the SQL into the file again. 4. Call `dashboard_screenshot` with the path. Look at the image. Fix layout, axis, format, and series problems in the file. 5. Repeat steps 3 and 4 at most two times. Stop when no issue remains, or after two loops. Report an issue you could not fix. 6. Reference the dashboard one time in the reply, directly under the finding it supports: `[Revenue overview](artifacts/revenue.dashboard.json)`. Do not describe chart values in prose that the dashboard already shows.

Edit a published dashboard

When the user asks to edit, update, or change a dashboard that already exists, do not write a new file from scratch. Load the published one.

1. Call `dashboard_list_published`. Find the dashboard by name, slug, or description. If none matches, tell the user which dashboards exist. 2. Call `dashboard_load_published` with the id or slug. It writes `artifacts/<slug>.dashboard.json` and the snapshot of every SQL dataset from the current version. The result names the file path and the row count of each dataset. 3. Edit that file. Keep the chart ids that stay. Add, remove, or change charts, filters, and datasets as the user asked. 4. For each dataset whose SQL or connection you changed, call `sp.dashboard_dataset` in the notebook with the new SQL. Copy the same SQL into the file. Unchanged datasets keep their loaded snapshots. 5. Call `dashboard_sample_data` with the path and all chart ids. Fix every issue. 6. Call `dashboard_screenshot` with the path. Look at the image. Fix the layout. 7. Reference the file one time in the reply: `[Title](artifacts/<slug>.dashboard.json)`. 8. Tell the user to publish the file as a new version of the same dashboard from the chat panel. Do not create a second dashboard.

Worked example

The notebook cell:

monthly_sql = """
with monthly as (
  select
    date_trunc('month', order_date) as month,
    case
      when country in ('US', 'CA', 'MX') then 'North America'
      when country in ('GB', 'DE', 'FR', 'NL') then 'Europe'
      else 'Rest of world'
    end as region,
    sum(net_revenue) as revenue
  from fct_orders
  where order_status = 'completed' and order_date >= '2024-01-01'
  group by 1, 2
)
select
  month,
  region,
  revenue,
  sum(revenue) over (
    partition by region
    order by month
    rows between 11 preceding and current row
  ) as revenue_ttm
from monthly
where month >= '2025-01-01'
order by month, region
"""
monthly = sp.dashboard_dataset("monthly", connection="warehouse", sql=monthly_sql)
monthly.head()

The `CASE` maps countries to regions. The window function computes the trailing twelve month sum. The query reads from 2024 so the first months of 2025 have a full window, then keeps only 2025 rows. The dashboard file carries the same SQL:

{
  "version": 1,
  "title": "Revenue overview",
  "description":