# Agentdb Causal Explain

> Walk the causal graph in AgentDB to explain why two memories are connected, or trace a root cause. Use when the user asks "why did X happen", "what led to Y", or after an incident.

- Skill: `ruvnet-agentdb/agentdb-causal-explain` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ruvnet-agentdb/agentdb-causal-explain`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ruvnet-agentdb/agentdb-causal-explain/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ruvnet (https://skillmd.com/u/ruvnet-agentdb)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/ruvnet-agentdb/agentdb-causal-explain

---


# Causal Explain

Given a target memory (an episode, a failed test, an outgoing change), traverse the causal graph backwards through edges to surface the chain of preceding events that explain it.

## When to use

- "Why did this fail?"
- "What led to the regression?"
- "Trace the dependency chain for X."
- Incident postmortem — surface every step + decision that contributed.

## API

```
agentdb_causal_explain(
  targetMemoryId:  <id>
  maxDepth?:       3
  minConfidence?:  0.5
  edgeWeights?:    'uplift' | 'confidence' | 'product'   // ranking strategy
)
```

Returns a path or DAG of `(node, edge, node)` tuples ranked by combined `confidence × |uplift|`. Each step carries the relation (`caused`, `supersedes`, `depends-on`, etc.) so the explanation reads naturally.

## Output shape

```
Why did "deploy-2026-05-04 failed migration" happen?

  ┌─ skill[migrate-add-not-null-column]   confidence 0.92
  │     ─[supersedes]→ skill[v1: migrate-with-default]
  │     ─[caused]→     episode[long-running migration on 50M rows]
  │                          ─[caused]→ episode[deploy-2026-05-04 failed migration]
  │
  └─ adr[ADR-046: zero-downtime migration policy]   confidence 0.78
        ─[depends-on]→ skill[migrate-add-not-null-column]
```

## Use the investigator agent

For complex traces, dispatch the `agentdb-investigator` agent (this plugin) — it walks deeper, cross-references with hierarchical memory, and writes a postmortem-shaped report.

## Don't

- Don't traverse with `maxDepth > 5` casually — graph fan-out gets exponential and the bandit's confidence weights don't compensate.
- Don't ignore the `confidence` column. A high-uplift edge with confidence 0.3 is gossip, not evidence.