bruin-data/agent-resource-kit

anomaly-investigate

Use when a tracked metric spikes or dips but no pipeline error and no quality check fired, or when someone asks why a number moved on a particular day.

Quelltext ansehen

Verwendung

  1. Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
  2. Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
  3. Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/bruin-data/agent-resource-kit --skill anomaly-investigate

Vor dem Start

  • Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
  • Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Originales Skill-Dokument

Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.

Anomaly investigate

Status: experimental · Risk: read-only

Upstream documentation wins. Where this file disagrees with the Bruin docs or bruin --help, upstream is right and this file is stale. Written against Bruin CLI v0.11.765, checked 2026-09-30.

The asset ran. The checks passed. The number still looks wrong. This skill finds out why by attribution, not by guesswork.

Look it up live

This file says what to reach for and what to be careful about. For the facts themselves, ask the tool, and tell the user if it disagrees with this file:

  • Flags: bruin <command> --help. The docs lag the CLI. For this skill,

bruin query --help and bruin lineage --help.

  • Docs: the local Bruin MCP server, bruin_get_doc_content('<path>'), or

https://getbruin.com/docs/bruin/<path>.html without it. For this skill: commands/query for warehouse queries, commands/lineage for upstreams and downstreams, and commands/cloud for runs and instances.

  • The user's environment: Bruin Cloud MCP, or

bruin cloud ... --output json.

Access

Use bruin cloud ... --output json, or the Bruin Cloud MCP server when the host has it, for run and asset context. Local repository inspection is allowed for metric definitions, lineage and git history. Local operational runs are not.

Credentials. Never ask for one in chat or pass one as a command argument. For a source, the user runs bruin connections add with no flags (the interactive prompt; its flag mode puts the secret on the command line) or references ${VAR} in .bruin.yml. For Cloud, bruin cloud login or an exported BRUIN_CLOUD_API_KEY, never --api-key. bruin auth status shows which is active without printing it.

When to use

  • A monitored metric sits well outside its expected range.
  • Someone asks why a number spiked or dropped on a given date.
  • `pipeline-triage` classified an issue as

anomaly.

  • A dashboard consumer reported that a number looks off.

Do not use for failed runs, which go to pipeline-diagnose; schema problems, which go to schema-drift-check; missing data, which goes to freshness-check; duplicated rows, which go to duplicate-investigate; or proving that a real-world business event happened. Those four skills ship with the CLI and install with bruin ai skills all.

Inputs

InputRequiredExampleNotes
metricyesmarts.daily_revenue.total_revenueMetric, or asset and column
windowyes2026-05-21A date or a range
project_idno<your-project-id>For Cloud run and asset context
pipelinenodaily-ordersInferred from the metric's asset where possible
dimensionsno[country, source, category]Inferred from the asset's columns otherwise
baselinenolast_28d_same_dowDefault: same day of week over four weeks, median

Context to gather

  1. Metric history. At least 28 days of daily values plus the window in

question, through bruin query.

  1. Baseline. Median and interquartile range over the baseline window, using

the same day of week where seasonality matters.

  1. Magnitude. How many IQRs or sigmas off, and the absolute delta. Both

matter: a large percentage on a tiny base is noise.

  1. Dimension breakdowns. The metric sliced by each candidate dimension,

window against baseline. Find where the anomaly concentrates.

  1. Cloud context. The runs, their diagnosis and the asset instances for

that window. "Checks passed" means the run status is success and the asset instance is neither failed nor checks_failed, depending on which response you are reading.

  1. Upstream row counts. Did the source row count move on that date?
  2. Upstream distributions. Did a column's distribution shift even though

the row count held steady?

  1. Code changes. git log and recent PRs on the metric's asset and its

upstreams over the last 30 days.

  1. Lineage. bruin lineage on the metric's asset, with the full upstream

and downstream set and the variant where the pipeline uses variants.

  1. External calendar. Holidays, launches, maintenance windows, paid

acquisition pulses. If no calendar is available, record this as "not checked" rather than omitting it.

Every warehouse query is read-only and carries a --description for the audit trail. Always pass --limit: its default is 0, which returns every row. Run --dry-run first on wide scans. Never pass --dangerously-bypass-soft-limits without explicit approval.

Attribution patterns

PatternSignalWhat it means
single-dimension-driverOne dimension value accounts for over half the deltaThat segment moved. Report it
pipeline-double-countUpstream row count is normal but the metric is a multipleA pipeline defect. Route to duplicate-investigate
pipeline-undercountUpstream rows dropped with no logged source failureThe interval is incomplete. Route to freshness-check
new-segmentThe delta comes entirely from a value absent from the baselineSomething launched. Confirm against the calendar
lost-segmentA previously present value disappearedSource dropped it, or collection stopped. Escalate
seasonality-not-modelledThe date recurs (month end, payday, holiday) and prior occurrences show the same shapeThe baseline is wrong, not the data
definitional-changeA recent commit changed how the metric is computedThe number is right under the new definition. Surface the commit
upstream-distribution-shiftRow count steady, distribution movedOften a real business change. Report without claiming cause
unexplainedNothing above attributes more than half the deltaSay so, with the full breakdown

Method

Pull the history, compute the baseline, measure the observed value. If the magnitude is within noise on both the relative and the absolute test, stop and return within-noise; a small move is not an anomaly just because someone asked about it.

Otherwise slice by every candidate dimension, pull upstream row counts and distributions, read the last 30 days of commits on the metric's lineage, and attribute the delta. Coverage above 50% is anomaly-explained. Below that it is anomaly-unexplained, and it must be reported that way.

Guardrails

  • Allowed: reading metric and asset data, inspecting Cloud state, running

capped read-only slicing queries, reading git and PR history, writing the report to .context/.

  • Requires approval: nothing. This skill is read-only.
  • Never: local operational runs; claiming a cause with no evidence link;

"correcting" anomalous data; suppressing the anomaly from a dashboard or an alert; attributing more than 100% of the delta, which is the usual failure when overlapping dimensions get double-counted.

Verification

This skill's output is verified by what happens next. If a pipeline cause was attributed, the follow-up fix should return the metric to baseline; if it does not, the attribution was wrong. If a real-world cause was attributed, no fix is expected, the metric holds at its new level, and the baseline needs updating. Record the outcome on the report so attribution accuracy can be tracked over time.

Output

Write .context/anomaly-<metric>-<window>-<timestamp>.yml and return the path.

yaml
metric: marts.daily_revenue.total_revenue
window: 2026-05-21
magnitude:
  observed: 4_812_000
  baseline_median: 2_140_000
  abs_z_score: 4.8
  delta_pct: +124.9
primary_drivers:
  - dimension: country
    value: <country-code>
    contribution_pct: 78
coverage_pct: 92
unexplained_pct: 8
recent_commits_examined: 6
recent_commits_relevant: 0
attribution: single-dimension-driver + upstream-distribution-shift
recommended_next:
  action: human-review
  note: Concentrated in one country. No pipeline action recommended.

A report with coverage below 50% is unexplained. Say so. Do not stretch the attribution to make the report look finished. Then call `pipeline-report`.

aus demselben Repository

Weitere Skills

Alle Skills