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/common-root-causes.md
View on GitHub# Common Root Cause Catalog
After gathering evidence, match your findings against these known root cause patterns. Each pattern has a signature (what the evidence looks like) and a typical fix.
## ETL & Pipeline Causes
### Pipeline scheduling failure
**Signature:** Table freshness delayed. No write queries in the expected window. ETL platform shows task failure or no task execution.
**Fix:** Check pipeline scheduler (cron, Airflow scheduler, dbt Cloud). Restart the job. Check for permission changes on the service account.
### Upstream cascade
**Signature:** Table is stale AND at least one upstream table is also stale. The upstream staleness started first.
**Fix:** Fix the upstream table first — this table will refresh automatically once its input is fresh.
### Resource contention / timeout
**Signature:** Queries are running but taking much longer than usual. Pipeline timeouts. Warehouse queue depth is high.
**Fix:** Scale the warehouse, optimize the query, or schedule during off-peak hours.
### Permission / credential change
**Signature:** Queries fail with "access denied" or "permission denied" errors. Worked fine before a specific date.
**Fix:** Check service account permissions. Re-grant access to the source data.
---
## Query & Code Causes
### Query regression
**Signature:** Query text changed around the time of the incident. New SQL produces different output (more/fewer rows, different values, nulls).
**Fix:** Review the query change. Revert or fix the SQL. Compare old vs new output.
### JOIN cardinality change
**Signature:** Row count changed dramatically. Query change shows JOIN modification (INNER ↔ LEFT, new JOIN added, JOIN key changed).
**Fix:** Review the JOIN logic. Check for fanout (1-to-many producing duplicates) or dropped rows (INNER JOIN filtering more than expected).
### Filter/WHERE clause change
**Signature:** Row count dropped or spiked. Query change shows WHERE clause modification.
**Fix:** Review the filter logic. Check if the filter is too restrictive or too permissive.
---
## Data Quality Causes
### Source data quality issue
**Signature:** Upstream table has unexpected values. Field lineage traces the bad data to a specific upstream column. The upstream column has new NULL values, outliers, or unexpected categories.
**Fix:** Fix the upstream data. Add data quality checks (validation monitors) at the source.
### Late-arriving data / backfill
**Signature:** Volume spike. New rows have old timestamps (data arrived late). No query change.
**Fix:** This may be intentional (backfill). Verify with the team. Adjust monitoring windows if needed.
### Schema drift
**Signature:** Source system changed its schema (added/removed columns, changed types). Downstream ETL failed or produced wrong results.
**Fix:** Update the ETL to handle the new schema. Add schema change monitors on the source.
---
## Infrastructure Causes
### Warehouse suspension / auto-suspend
**Signature:** Queries queued for a long time, then ran. Freshness delay matches the warehouse suspension period.
**Fix:** Adjust warehouse auto-suspend settings, or schedule a warm-up query before the critical pipeline.
### Cluster/compute failure
**Signature:** Databricks cluster failed to start, Airflow worker crashed, dbt Cloud runner timed out.
**Fix:** Check infrastructure logs. Scale the compute. Retry the job.
### Network / connectivity issue
**Signature:** Intermittent failures across multiple tables. Error messages mention timeouts, connection refused, or DNS resolution.
**Fix:** Check network connectivity. Review cloud provider status page.
---
## How to use this catalog
1. After gathering evidence in Steps 1-6 of the main workflow, review the signatures above.
2. Match your evidence to the closest pattern.
3. Present the root cause with the specific evidence that matched.
4. Suggest the fix from the catalog, adapted to the user's specific situation.
5. If no pattern matches, say so — novel root causes do exist. Present the evidence and let the user draw conclusions.
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: 471k | 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 |