Skip to content

monte-carlo-data/mc-agent-toolkit / skills/analyze-root-cause

monte-carlo-analyze-root-cause

Verified

Investigate data incidents and find root causes using Monte Carlo's observability data. Guides the agent through systematic investigation: alert lookup, lineage tracing, ETL checks, query analysis, and data profiling. Activates when a user asks about data issues, incidents, alerts, or why data looks wrong.

references/freshness-investigation.md

View on GitHub
# Freshness Investigation Playbook

Use this when a table hasn't updated on its expected schedule.

## Investigation steps

### 1. Confirm the freshness delay

Call `get_table_freshness` with the table's `full_table_id` and `resource_id`. Also call `get_asset` with the same `full_table_id` — its response includes the table's `mcon`, which the lineage and query tools below need. Check:
- When was the last successful update?
- What's the normal update cadence? (hourly, daily, etc.)
- How long has the delay been?

### 2. Check the ETL pipeline

The table is populated by an ETL pipeline. Check if the pipeline failed:

**Airflow:**
- Call `get_etl_jobs` with `platform="airflow"` to find which DAGs/tasks write to this table
- Call `get_etl_issues` with `platform="airflow"` and a time range — look for task failures, retries, or SLA misses

**dbt:**
- Call `get_etl_jobs` with `platform="dbt"` to find which dbt jobs/models produce this table
- Call `get_etl_issues` with `platform="dbt"` — look for compilation errors, test failures, or timeouts

**Databricks:**
- Call `get_etl_jobs` with `platform="databricks"` to find relevant jobs
- Call `get_etl_issues` with `platform="databricks"` — look for notebook failures, cluster issues

### 3. Check the write queries

Call `get_queries(mcon=table_mcon, query_type="destination", start_time=..., end_time=...)`, with a window that covers the last expected update, to see recent write queries:
- Did write queries stop running entirely? → pipeline scheduling issue
- Did write queries run but with errors? → data or permission issue
- Did write queries run successfully but produce no rows? → upstream data issue

### 4. Check upstream freshness

Call `get_asset_lineage(mcons=[table_mcon], direction="UPSTREAM")` to find upstream tables, then:
- Call `get_table_freshness` on each upstream table
- If an upstream table is also stale, the issue is propagating from there
- Recurse upstream until you find the root source of the delay

### 5. Check ETL job performance

Call `get_jobs_performance` to check if the ETL job's runtime has degraded:
- Is the job taking longer than usual? (compare `avgDuration` to 7-day trend)
- Is the job failing more often? (check `failureRate`)
- Is the job currently running or stuck? (check last run status)
- A job that's running but taking 3x longer than normal may explain the freshness delay without an outright failure

Also call `get_etl_jobs` with the relevant `platform` and the table MCONs to find which specific jobs write to this table, then check their issues with `get_etl_issues`.

### 6. Check for query changes

Call `get_query_changes` — did someone modify the ETL query recently?
- New JOINs that produce empty results
- Changed WHERE clauses that filter out all data
- Modified schedule or dependency

## Common root causes

- **Pipeline scheduling failure** — cron job stopped, DAG was paused, permissions revoked
- **Upstream freshness cascade** — an upstream table is stale, blocking this table's refresh
- **Query timeout** — the refresh query is taking too long and timing out
- **Resource contention** — warehouse is overloaded, queries are queued
- **Permission change** — service account lost access to source data
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall