/causal-dag-builder

name: causal-dag-builder
description: Build a refinable causal DAG before answering "did X cause Y" on observational data. Emits a Mermaid diagram of assumed causes, applies the back-door criterion to decide what to condition on, and forces confounders, mediators, and colliders to be named explicitly instead of "controlling for everything". The DAG is an artifact downstream skills read to pick the right adjustment set. Use whenever interpreting cohort comparisons, funnel drop-offs, or any analytics result where the user is reasoning causally without an experiment. Pairs with analytics-diagnostic-method as the causal-structure layer underneath the diagnostic tree. Triggers when Clamp MCP cohorts_compare or funnels_create is called with no experimental holdback, when a Clamp MCP result prompts a causal claim from observational data, or when via Clamp the user asks "why did this segment convert higher".
when_to_use: When the user makes a causal claim from observational data — "users who do X convert higher", "feature A drove the lift", "this channel is better" — and there is no random assignment behind the comparison. Also when a cohort comparison, funnel, or retention curve is about to be interpreted and the causal structure has not been laid out yet.

Causal DAG builder

Observational analytics tempts everyone into two mistakes: assuming correlation is cause, and "controlling for everything" to launder it. Both mistakes go away when the assumed causal structure is written down first. A DAG forces the assumptions onto paper, where they can be argued with. This skill emits one, refines it as evidence arrives, and uses the back-door criterion to pick the adjustment set — instead of throwing every available variable into a regression.

When NOT to use this

• The comparison is a properly-randomised A/B test with clean exposure events. Randomisation handles confounding by construction; the DAG adds nothing. Use `experiment-result-reader` instead.
• The user is asking a descriptive question ("how many users converted last week?"), not a causal one. Descriptive answers don't need causal structure.
• The DAG would have a single arrow (X → Y, no other variables in the system). That's not a DAG, that's an assertion. Either there genuinely are no other variables (rare) or the modeller hasn't thought hard enough yet.
• The dataset is so thin that no adjustment set has support. A DAG can tell you which variables to condition on; it cannot conjure rows that aren't there.

What a DAG is, in 100 words

A causal DAG is a directed acyclic graph where **nodes are variables** and **arrows mean "directly causes"** (in the modeller's belief, not in the data). Acyclic = no variable causes itself through a loop. The DAG encodes **assumptions**, not facts; it is the modeller's hypothesis about the data-generating process, drawn so others can attack it. The point is not the picture. The point is that once the structure is explicit, the back-door criterion mechanically tells you which variables to condition on to estimate a causal effect — and, just as important, which variables you must **not** condition on.

The three structural patterns

Every triple of nodes in a DAG is one of three shapes. Conditioning rules differ for each.

| Pattern | Shape | Role of middle node | Condition on it? | |---|---|---|---| | Chain | X → M → Y | Mediator | **No** (over-adjustment: blocks the effect you're trying to measure) | | Fork | X ← C → Y | Confounder | **Yes** (blocks a back-door path that would otherwise bias the estimate) | | Collider | X → C ← Y | Collider | **No** (opens a spurious path that wasn't there) |

The asymmetry is the whole game. "Control for everything available" is wrong because it silently conditions on mediators and colliders. The DAG is the bookkeeping that prevents that.

The back-door criterion

To estimate the causal effect of X on Y from observational data, find a set of variables Z such that:

1. Z **blocks every back-door path** from X to Y. A back-door path is any path from X to Y that starts with an arrow pointing **into** X (i.e. goes through a common cause of X and Y). 2. Z **contains no descendants of X**. (Conditioning on a descendant of X often opens a collider path or blocks a mediator.) 3. Z does **not open any collider path** that was previously blocked.

If such a Z exists, conditioning on Z is sufficient to recover the causal effect. If no such Z exists from observed variables, the effect is **not identifiable** from this data — and no amount of regression will fix that. Saying so is a real answer.

Method

Phase 1. Name the causal question

Before drawing anything, state the question in the form **"does X cause Y, and by how much?"** with X and Y written as observable variables. If the user said "users who visit /pricing convert higher", X = visited_pricing_page (binary), Y = converted (binary). If the user said "feature A drove the lift", X = used_feature_A, Y = the conversion metric they care about.

If X and Y can't be written down concretely, the question isn't ready for a DAG. Push back and ask the user to nail the variables before the structure.

Phase 2. List candidate variables

Brainstorm the variables the modeller believes might matter. For each, label which of these it is:

• **Plausible cause of X** (would push someone toward the behaviour)
• **Plausible cause of Y** (would push someone toward the outcome)
• **Caused by X** (downstream of the behaviour)
• **Caused by Y** (downstream of the outcome)
• **Caused by both X and Y** (collider — flag and remember)

The same variable can appear in multiple buckets; that's where structure comes from. Don't censor at this stage; capture the modeller's beliefs, even ones that contradict each other. The DAG arbitrates next.

Phase 3. Draw the minimal DAG in Mermaid

Emit the DAG as Mermaid so it lives in the chat as a refinable artifact. Concrete syntax:

graph LR
  intent[user_intent_to_