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/volume-investigation.md

View on GitHub
# Volume Investigation Playbook

Use this when a table's row count changed unexpectedly (spike or drop).

## Investigation steps

### 1. Quantify the change

Call `get_table_size_history` with the table's `full_table_id` and `resource_id`:
- What was the row count before and after?
- When exactly did the change occur?
- Is this a sudden jump or a gradual trend?
- Compare to the normal pattern (seasonality field may help)

### 2. Check for query changes

Call `get_query_changes` — did the ETL query change around the time of the volume shift?
- New or removed WHERE clauses can dramatically change row counts
- Changed JOINs (INNER → LEFT, or vice versa) affect output volume
- Modified deduplication logic

Call `get_change_timeline` for a unified view of all changes correlated with the volume shift.

### 3. Check upstream volume

Call `get_asset_lineage(mcons=[table_mcon], direction="UPSTREAM")` to find source tables.
For each upstream table:
- Call `get_table_size_history` — did the source data volume also change?
- If upstream volume changed proportionally, the issue is in the source data, not this table's ETL

### 4. Check for failed/futile queries

Call `get_query_rca` with the table MCONs and a time range:
- **Failed queries** with new error types may indicate broken inserts
- **Futile queries** (ran but produced nothing) may explain missing rows
- **QDR (query didn't run)** may explain why expected data wasn't loaded

### 5. Profile the data (if DB connector available)

If a database MCP server is connected:
- Compare row counts by date partition: `SELECT date_col, COUNT(*) FROM table GROUP BY 1 ORDER BY 1`
- Check for duplicate rows that appeared: `SELECT *, COUNT(*) FROM table GROUP BY ALL HAVING COUNT(*) > 1`
- Check if specific segments grew/shrank: group by key dimensions
- See `references/data-exploration.md` for more SQL patterns

## Common root causes

- **Source data volume change** — upstream system sent more/fewer records than usual
- **Filter change** — ETL WHERE clause was modified, including/excluding different rows
- **Dedup logic change** — deduplication rules changed, producing more or fewer unique rows
- **Late-arriving data** — backfill or reprocessing loaded historical data
- **Partition swap** — a full partition was replaced with different data
- **Schema migration** — table was truncated and reloaded as part of a migration
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