@dataworks-technology/cli 1.4.1 → 1.6.0

package/plugins/dataworks/skills/query-dataworks-metrics/SKILL.md

@@ -1,12 +1,15 @@
 ---
 name: query-dataworks-metrics
-description: Query historical Dataworks athlete metrics such as GPS, heart rate, speed, altitude, cadence, power, timing, or custom metrics. Use when a user asks for latest, last, recent, or time-bounded metric values for an athlete by ID or name.
+description: Query historical Dataworks metrics such as GPS, heart rate, speed, altitude, cadence, power, timing, or custom metrics, for one athlete or across a whole event. Use when a user asks for latest, last, recent, or time-bounded metric values, or needs to find an athlete or event ID.
 ---
 
 # Query Dataworks metrics
 
-Use the `query_metrics` tool. It is read-only and uses the current authenticated
-`dw` session and selected tenant.
+Three read-only tools use the current authenticated `dw` session and tenant:
+
+- `query_metrics` — metric values, scoped to an athlete, an event, or a datasource.
+- `list_athletes` — find an athlete ID, or confirm someone is not in this tenant.
+- `list_events` — find an event ID for a race, by name.
 
 If `query_metrics` is unavailable, tell the user to run `dw agents install`
 once in their terminal, then start a new Codex thread or run `/reload-plugins`
@@ -14,18 +17,42 @@ in Claude Code. Do not substitute raw GraphQL or guess that setup succeeded.
 
 ## Construct the request
 
-- Pass `athlete_id` when the user provides a Dataworks athlete public ID.
-- Otherwise pass `athlete_name`; let the tool resolve it and surface ambiguity.
+- Scope every query. Pass at least one of `athlete_id`, `athlete_name`,
+  `event_id`, or `dataset_datasource_id`; the tool refuses an unscoped query
+  rather than sweeping the tenant.
+- For a question about a person, pass `athlete_id` when the user gives an ID,
+  otherwise `athlete_name` and let the tool resolve it.
+- For a question about a race or feed — "the latest heart rate at T100 San
+  Francisco" — omit the athlete entirely and pass `event_id`. Do not invent an
+  athlete to satisfy the call. Rows still carry `athlete_id` per value.
+- To compare people, pass `athlete_ids` rather than one query each; combined
+  with `aggregate` it returns one value per athlete. Use `event_ids` likewise to
+  span a series of races. Resolve names to IDs with `list_athletes` first, and
+  note an athlete with no data simply has no rows rather than an error.
 - Map the user's wording onto a canonical metric name from the catalogue below.
   Case, spaces, hyphens and underscores are ignored, so "Heart Rate" resolves to
   `heartrate`. Do not invent a metric name.
 - Default to `limit: 30` and `order: newest` only when the user did not specify
   a count or order.
 - Preserve explicit `from` and `to` times as ISO 8601 date-times.
-- Pass `event_id`, `dataset_datasource_id`, or `tenant_id` only when explicitly
-  supplied or already resolved. Never guess an ID.
+- Never guess or infer an ID. Resolve one with `list_athletes` or `list_events`,
+  or use an ID the user supplied. An ID inferred from a shared prefix, a naming
+  pattern, or a row count is a guess: say you could not resolve it instead.
 - For a genuinely custom metric absent from the catalogue, pass its exact name
   and an explicit `metric_category`.
+- Rows carry every column the metric's category provides. Heart rate and power
+  add rolling `max`, `min`, `avg` and a seven-zone breakdown, all under `extra`
+  on each row — read zones from there rather than computing them.
+- To find high or low readings, pass `min_value` or `max_value` rather than
+  fetching everything and filtering; the server applies the bound.
+- To rank by value rather than recency, pass `order_by: "current"`. It defaults
+  to `timestamp`, and `order` controls the direction either way.
+- For a maximum, minimum, average, sum, or count, pass `aggregate` instead of
+  fetching rows and computing it yourself. The server aggregates over every
+  matching sample; taking a maximum over returned rows only covers the rows
+  `limit` allowed through. Results arrive in `aggregate.groups` and `rows` is
+  empty. `group_by` defaults to `athletepublicid`, so an event-scoped aggregate
+  returns one value per athlete; pass `eventpublicid` for one value per event.
 
 ## Metric catalogue
 
@@ -55,6 +82,20 @@ Haigh"`, `metric: "GPS"`, `limit: 30`, `order: "newest"`.
   `metric: "heartrate"`, then take the maximum over the returned rows.
 - “Cadence for Sam since noon” → `athlete_name: "Sam"`, `metric: "cadence"`,
   `from: <the unambiguous ISO 8601 time requested>`.
+- “Latest 10 heart rate values for T100 San Francisco” → `list_events` with
+  `search: "T100 San Francisco"` to get the ID, then `query_metrics` with
+  `event_id: <that ID>`, `metric: "heartrate"`, `limit: 10`, and no athlete.
+- “Hayden Wilde's maximum heart rate” → `query_metrics` with
+  `athlete_name: "Hayden Wilde"`, `metric: "heartrate"`, `aggregate: "max"`.
+  Read the answer from `aggregate.groups`; do not fetch rows and compare them.
+- “When was Sam above 180bpm?” → `metric: "heartrate"`, `min_value: 180`.
+- “Sam's highest heart rate readings” → `metric: "heartrate"`,
+  `order_by: "current"`, which ranks by value instead of recency.
+- “Sam's heart rate zones” → an ordinary query; read `extra.z1_percentage`
+  through `extra.z7_percentage` from any returned row.
+- “Compare Hayden and Sam's peak heart rate” → `list_athletes` for both IDs,
+  then one call with `athlete_ids: [<both>]`, `metric: "heartrate"`,
+  `aggregate: "max"`; each athlete appears once in `aggregate.groups`.
 
 ## Handle results
 
@@ -63,8 +104,20 @@ environment, tenant, canonical metric, order, and returned count. GPS rows inclu
 decoded `position.latitude` and `position.longitude`; heart-rate values are
 numeric with unit `bpm` when the source value is valid.
 
-If the tool reports `ATHLETE_AMBIGUOUS`, present its candidates and ask the user
-to choose. For `AUTH_REQUIRED` or `TENANT_REQUIRED`, follow the recovery command
+Every error carries a `recovery` field. Follow it rather than improvising, and
+never fall back to raw GraphQL or `dw data ...` to work around a failure.
+
+- `ATHLETE_AMBIGUOUS` — present the candidates and ask the user to choose.
+- `ATHLETE_NOT_FOUND` — the athlete is not in this tenant. Do not retry with
+  name variations. Call `list_athletes` once to check, then tell the user.
+- `QUERY_SCOPE_REQUIRED` — add an athlete, `event_id`, or
+  `dataset_datasource_id`.
+- `METRIC_CATEGORY_REQUIRED` — retry with one of the returned `suggestions`.
+
+`list_events` reports where its results came from in `source`: the events API,
+or each dataset's event relation. Either is authoritative. Only when
+`unavailable: true` did both routes yield nothing — report that and stop rather
+than identifying an event some other way. For `AUTH_REQUIRED` or `TENANT_REQUIRED`, follow the recovery command
 in the error and retry. For `METRIC_CATEGORY_REQUIRED`, the error's `suggestions`
 list the closest canonical names — retry with one rather than asking the user to
 spell the metric. Never expose credentials or session material.