Exp Lens Causal Assumptions

Causal Assumptions Experimental Design Lens

Philosophical Mode: Causal-Structural Primary Question: "What causal assumptions support this design?" Focus: Confounders, Mediators, Colliders, Adjustment Sets, Identification Strategy

When to Use

• Experiment claims causal effects
• Pipeline has shared components that might confound
• Need to verify identification strategy
• User invokes /exp-lens-causal-assumptions or /make-experiment-diag causal

Critical Constraints

NEVER:

• Modify any source code files
• Do not litter the codebase with useless comments, TODO markers, or explanatory annotations — the skill output and diagram speak for themselves

ALWAYS:

• Classify every variable as Treatment, Outcome, Confounder, Mediator, Collider, Instrument, or Selection variable
• Map every directed edge to a concrete code-level data flow
• Flag all unblocked backdoor paths explicitly
• Document the identification strategy with testable assumptions
• BEFORE creating any diagram, LOAD the /mermaid skill using the Skill tool - this is MANDATORY

Analysis Workflow

Step 1: Launch Parallel Exploration Subagents

Spawn Explore subagents to investigate:

Treatment & Outcome Definition

• Find experiment config, treatment assignment code, outcome measurement
• Look for: treatment, control, outcome, response, endpoint, metric

Confounding Pathways

• Find shared data sources, preprocessing, environment variables
• Look for: shared, common, config, environment, seed, global

Mediator & Mechanism Variables

• Find intermediate processing steps between treatment and outcome
• Look for: transform, preprocess, feature, intermediate, pipeline

Collider & Selection Variables

• Find filtering, subsetting, or conditional logic applied post-treatment
• Look for: filter, subset, exclude, condition, threshold, select

Randomization & Assignment

• Find how experimental units are assigned to conditions
• Look for: random, assign, allocate, split, stratify, block

Step 2: Build the Causal Graph Structure

For each variable identified, classify as: Treatment, Outcome, Confounder, Mediator, Collider, Instrument, or Selection variable. Map directed edges based on code-level data flow. Flag any unblocked backdoor paths.

Step 3: Identify Causal Assumptions

CRITICAL — Analyze Claim Direction: For every edge in the causal graph, determine:

• Does code implement a causal mechanism (A produces B) or merely a statistical association?
• Is the direction grounded in temporal ordering or domain knowledge?
• Are there feedback loops?

Document each assumption as either testable or untestable, and record the evidence (or lack of evidence) from the codebase.

Step 4: Create the Diagram

Use flowchart with:

Direction: TB (causes flow downward to effects)

Subgraphs:

• TREATMENT ASSIGNMENT
• MEDIATING MECHANISMS
• OUTCOME MEASUREMENT
• CONFOUNDERS
• SELECTION/COLLIDERS

Node Styling:

• cli class: Treatment variables
• output class: Outcome variables
• handler class: Mediators
• stateNode class: Confounders
• detector class: Colliders and selection variables
• gap class: Unblocked backdoor paths
• newComponent class: Instruments

Edge Labels: causal, confounds, selects, mediates, blocks

Step 5: Write Output

Write the diagram to: temp/exp-lens-causal-assumptions/exp_diag_causal_assumptions_{YYYY-MM-DD_HHMMSS}.md

Output Template

# Causal Assumptions Diagram: {Experiment Name}

**Lens:** Causal Assumptions (Causal-Structural)
**Question:** What causal assumptions support this design?
**Date:** {YYYY-MM-DD}
**Scope:** {What was analyzed}

## Causal Variables

| Variable | Type | Measured? | Controlled? |
|----------|------|-----------|-------------|
| {name} | {Treatment/Outcome/Confounder/Mediator/Collider/Instrument/Selection} | {Yes/No} | {Yes/No} |

## Causal DAG

```mermaid
%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 60, 'curve': 'basis'}}}%%
flowchart TB
    %% CLASS DEFINITIONS %%
    classDef cli fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
    classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
    classDef newComponent fill:#2e7d32,stroke:#81c784,stroke-width:2px,color:#fff;
    classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;
    classDef gap fill:#ff6f00,stroke:#ffa726,stroke-width:2px,color:#000;
    classDef integration fill:#c62828,stroke:#ef9a9a,stroke-width:2px,color:#fff;

    subgraph Confounders ["CONFOUNDERS"]
        CONF["Confounder Variable<br/>━━━━━━━━━━<br/>Shared source<br/>Controlled?"]
    end

    subgraph Treatment ["TREATMENT ASSIGNMENT"]
        TREAT["Treatment<br/>━━━━━━━━━━<br/>Assignment mechanism<br/>Randomized?"]
        INSTR["Instrument<br/>━━━━━━━━━━<br/>Exclusion restriction"]
    end

    subgraph Mediators ["MEDIATING MECHANISMS"]
        MED["Mediator<br/>━━━━━━━━━━<br/>Intermediate step"]
    end

    subgraph Outcome ["OUTCOME MEASUREMENT"]
        OUT["Outcome<br/>━━━━━━━━━━<br/>Metric / endpoint"]
    end

    subgraph Selection ["SELECTION/COLLIDERS"]
        COLL["Collider<br/>━━━━━━━━━━<br/>Post-treatment filter"]
    end

    %% CAUSAL EDGES %%
    CONF -->|"confounds"| TREAT
    CONF -->|"confounds"| OUT
    INSTR -->|"causal"| TREAT
    TREAT -->|"causal"| MED
    MED -->|"mediates"| OUT
    TREAT -->|"selects"| COLL
    OUT -->|"selects"| COLL

    %% CLASS ASSIGNMENTS %%
    class TREAT cli;
    class OUT output;
    class MED handler;
    class CONF stateNode;
    class COLL detector;
    class INSTR newComponent;

Color Legend:

Identification Strategy

Unblocked Backdoor Paths

---

## Pre-Diagram Checklist

Before creating the diagram, verify:

- [ ] LOADED `/mermaid` skill using the Skill tool
- [ ] Using ONLY classDef styles from the mermaid skill (no invented colors)
- [ ] Diagram will include a color legend table

---

## Related Skills

- `/make-experiment-diag` - Parent skill for lens selection
- `/mermaid` - MUST BE LOADED before creating diagram
- `/exp-lens-estimand-clarity` - For clarifying the target estimand
- `/exp-lens-validity-threats` - For broader validity threat inventory