monte-carlo-data/mc-agent-toolkit / skills/analyze-root-cause
monte-carlo-analyze-root-cause
VerifiedInvestigate 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.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 4.7 KB |
| SKILL.md | skill md | 15.9 KB |
| references/common-root-causes.md | markdown | 4.0 KB |
| references/data-exploration.md | markdown | 4.8 KB |
| references/etl-failure-investigation.md | markdown | 2.7 KB |
| references/field-anomaly-investigation.md | markdown | 4.0 KB |
| references/freshness-investigation.md | markdown | 3.2 KB |
| references/intake-no-incident.md | markdown | 3.5 KB |
| references/query-change-investigation.md | markdown | 2.2 KB |
| references/schema-investigation.md | markdown | 1.8 KB |
| references/volume-investigation.md | markdown | 2.4 KB |
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |