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
Arguments
/autoskillit:exp-lens-causal-assumptions [context_path] [experiment_plan_path]
- context_path (optional positional arg 1) — Absolute path to a lens context file
containing IV/DV tables, H0/H1 hypotheses, controlled variables, and success criteria.
If provided, read this file before beginning analysis to obtain structured context.
If omitted, discover context by exploring the CWD.
- experiment_plan_path (optional positional arg 2) — Absolute path to the full
experiment plan. If provided, read for complete experimental methodology and design.
If omitted, locate the experiment plan by exploring the CWD.
When to Use
- Experiment claims causal effects
- Pipeline has shared components that might confound
- Need to verify identification strategy
- User invokes
/autoskillit:exp-lens-causal-assumptions or /autoskillit: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
- Create files outside
{{AUTOSKILLIT_TEMP}}/exp-lens-causal-assumptions/
- Run subagents in the background (
run_in_background: true is prohibited)
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 /autoskillit:mermaid skill using the Skill tool - this is MANDATORY
If the Skill tool cannot be used (disable-model-invocation) or refuses this invocation, do NOT proceed with diagram creation. Abort this step and omit the diagram from output.
Write output to {{AUTOSKILLIT_TEMP}}/exp-lens-causal-assumptions/exp_diag_causal_assumptions_{YYYY-MM-DD_HHMMSS}.md
After writing the file, emit the structured output token as literal plain text with no
markdown formatting on the token name (the adjudicator performs a regex match):
diagram_path = /absolute/path/to/{{AUTOSKILLIT_TEMP}}/exp-lens-causal-assumptions/exp_diag_causal_assumptions_{...}.md
Analysis Workflow
Step 0: Parse optional arguments
If positional arg 1 (context_path) is provided and the file exists, read it to obtain
IV/DV tables, H0/H1 hypotheses, controlled variables, and success criteria. If positional
arg 2 (experiment_plan_path) is provided and exists, read the experiment plan for full
methodology. Use this structured context as the foundation for Steps 1-5; skip the CWD
exploration for these fields if the context file supplies them.
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: {{AUTOSKILLIT_TEMP}}/exp-lens-causal-assumptions/exp_diag_causal_assumptions_{YYYY-MM-DD_HHMMSS}.md (relative to the current working directory)
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:
| Color |
Category |
Description |
| Dark Blue |
Treatment |
Treatment assignment variables |
| Dark Teal |
Outcome |
Outcome measurement variables |
| Orange |
Mediator |
Intermediate mechanism variables |
| Teal |
Confounder |
Shared causes of treatment and outcome |
| Red |
Collider/Selection |
Post-treatment filters (conditioning risk) |
| Green |
Instrument |
Variables affecting only treatment |
| Amber |
Backdoor Path |
Unblocked confounding path |
Identification Strategy
| Assumption |
Testable? |
Evidence |
| {assumption} |
{Yes/No} |
{evidence from codebase} |
Unblocked Backdoor Paths
| Path |
Variables |
Severity |
Mitigation |
| {path} |
{A -> ... -> B} |
{High/Medium/Low} |
{adjustment/unavailable} |
---
## Pre-Diagram Checklist
Before creating the diagram, verify:
- [ ] LOADED `/autoskillit: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
- `/autoskillit:make-experiment-diag` - Parent skill for lens selection
- `/autoskillit:mermaid` - MUST BE LOADED before creating diagram
- `/autoskillit:exp-lens-estimand-clarity` - For clarifying the target estimand
- `/autoskillit:exp-lens-validity-threats` - For broader validity threat inventory
1---2name: exp-lens-causal-assumptions3categories: [exp-lens]4activate_deps: [mermaid]5description: Create Causal Assumptions experimental design diagram showing confounders, mediators, colliders, and identification strategy. Causal-structural lens answering "What causal assumptions support this design?"6hooks:7 PreToolUse:8 - matcher: "*"9 hooks:10 - type: command11 command: "echo 'Causal Assumptions Lens - Tracing causal structure...'"12 once: true13metadata:14 source: https://skillmd.com/skills/talont-org/exp-lens-causal-assumptions15---1617# Causal Assumptions Experimental Design Lens1819**Philosophical Mode:** Causal-Structural20**Primary Question:** "What causal assumptions support this design?"21**Focus:** Confounders, Mediators, Colliders, Adjustment Sets, Identification Strategy2223## Arguments2425`/autoskillit:exp-lens-causal-assumptions [context_path] [experiment_plan_path]`2627- **context_path** (optional positional arg 1) — Absolute path to a lens context file28 containing IV/DV tables, H0/H1 hypotheses, controlled variables, and success criteria.29 If provided, read this file before beginning analysis to obtain structured context.30 If omitted, discover context by exploring the CWD.31- **experiment_plan_path** (optional positional arg 2) — Absolute path to the full32 experiment plan. If provided, read for complete experimental methodology and design.33 If omitted, locate the experiment plan by exploring the CWD.3435## When to Use3637- Experiment claims causal effects38- Pipeline has shared components that might confound39- Need to verify identification strategy40- User invokes `/autoskillit:exp-lens-causal-assumptions` or `/autoskillit:make-experiment-diag causal`4142## Critical Constraints4344**NEVER:**45- Modify any source code files46- Do not litter the codebase with useless comments, TODO markers, or explanatory annotations — the skill output and diagram speak for themselves47- Create files outside `{{AUTOSKILLIT_TEMP}}/exp-lens-causal-assumptions/`48- Run subagents in the background (`run_in_background: true` is prohibited)4950**ALWAYS:**51- Classify every variable as Treatment, Outcome, Confounder, Mediator, Collider, Instrument, or Selection variable52- Map every directed edge to a concrete code-level data flow53- Flag all unblocked backdoor paths explicitly54- Document the identification strategy with testable assumptions55- BEFORE creating any diagram, LOAD the `/autoskillit:mermaid` skill using the Skill tool - this is MANDATORY56- If the Skill tool cannot be used (disable-model-invocation) or refuses this invocation, do NOT proceed with diagram creation. Abort this step and omit the diagram from output.57- Write output to `{{AUTOSKILLIT_TEMP}}/exp-lens-causal-assumptions/exp_diag_causal_assumptions_{YYYY-MM-DD_HHMMSS}.md`58- After writing the file, emit the structured output token as **literal plain text** with no59 markdown formatting on the token name (the adjudicator performs a regex match):6061 ```62 diagram_path = /absolute/path/to/{{AUTOSKILLIT_TEMP}}/exp-lens-causal-assumptions/exp_diag_causal_assumptions_{...}.md63 ```6465---6667## Analysis Workflow6869### Step 0: Parse optional arguments7071If positional arg 1 (context_path) is provided and the file exists, read it to obtain72IV/DV tables, H0/H1 hypotheses, controlled variables, and success criteria. If positional73arg 2 (experiment_plan_path) is provided and exists, read the experiment plan for full74methodology. Use this structured context as the foundation for Steps 1-5; skip the CWD75exploration for these fields if the context file supplies them.7677### Step 1: Launch Parallel Exploration Subagents7879Spawn Explore subagents to investigate:8081**Treatment & Outcome Definition**82- Find experiment config, treatment assignment code, outcome measurement83- Look for: treatment, control, outcome, response, endpoint, metric8485**Confounding Pathways**86- Find shared data sources, preprocessing, environment variables87- Look for: shared, common, config, environment, seed, global8889**Mediator & Mechanism Variables**90- Find intermediate processing steps between treatment and outcome91- Look for: transform, preprocess, feature, intermediate, pipeline9293**Collider & Selection Variables**94- Find filtering, subsetting, or conditional logic applied post-treatment95- Look for: filter, subset, exclude, condition, threshold, select9697**Randomization & Assignment**98- Find how experimental units are assigned to conditions99- Look for: random, assign, allocate, split, stratify, block100101### Step 2: Build the Causal Graph Structure102103For 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.104105### Step 3: Identify Causal Assumptions106107**CRITICAL — Analyze Claim Direction:**108For every edge in the causal graph, determine:109- Does code implement a causal mechanism (A produces B) or merely a statistical association?110- Is the direction grounded in temporal ordering or domain knowledge?111- Are there feedback loops?112113Document each assumption as either testable or untestable, and record the evidence (or lack of evidence) from the codebase.114115### Step 4: Create the Diagram116117Use flowchart with:118119**Direction:** `TB` (causes flow downward to effects)120121**Subgraphs:**122- TREATMENT ASSIGNMENT123- MEDIATING MECHANISMS124- OUTCOME MEASUREMENT125- CONFOUNDERS126- SELECTION/COLLIDERS127128**Node Styling:**129- `cli` class: Treatment variables130- `output` class: Outcome variables131- `handler` class: Mediators132- `stateNode` class: Confounders133- `detector` class: Colliders and selection variables134- `gap` class: Unblocked backdoor paths135- `newComponent` class: Instruments136137**Edge Labels:** causal, confounds, selects, mediates, blocks138139### Step 5: Write Output140141Write the diagram to: `{{AUTOSKILLIT_TEMP}}/exp-lens-causal-assumptions/exp_diag_causal_assumptions_{YYYY-MM-DD_HHMMSS}.md` (relative to the current working directory)142143---144145## Output Template146147```markdown148# Causal Assumptions Diagram: {Experiment Name}149150**Lens:** Causal Assumptions (Causal-Structural)151**Question:** What causal assumptions support this design?152**Date:** {YYYY-MM-DD}153**Scope:** {What was analyzed}154155## Causal Variables156157| Variable | Type | Measured? | Controlled? |158|----------|------|-----------|-------------|159| {name} | {Treatment/Outcome/Confounder/Mediator/Collider/Instrument/Selection} | {Yes/No} | {Yes/No} |160161## Causal DAG162163```mermaid164%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 60, 'curve': 'basis'}}}%%165flowchart TB166 %% CLASS DEFINITIONS %%167 classDef cli fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;168 classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;169 classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;170 classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;171 classDef newComponent fill:#2e7d32,stroke:#81c784,stroke-width:2px,color:#fff;172 classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;173 classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;174 classDef gap fill:#ff6f00,stroke:#ffa726,stroke-width:2px,color:#000;175 classDef integration fill:#c62828,stroke:#ef9a9a,stroke-width:2px,color:#fff;176177 subgraph Confounders ["CONFOUNDERS"]178 CONF["Confounder Variable<br/>━━━━━━━━━━<br/>Shared source<br/>Controlled?"]179 end180181 subgraph Treatment ["TREATMENT ASSIGNMENT"]182 TREAT["Treatment<br/>━━━━━━━━━━<br/>Assignment mechanism<br/>Randomized?"]183 INSTR["Instrument<br/>━━━━━━━━━━<br/>Exclusion restriction"]184 end185186 subgraph Mediators ["MEDIATING MECHANISMS"]187 MED["Mediator<br/>━━━━━━━━━━<br/>Intermediate step"]188 end189190 subgraph Outcome ["OUTCOME MEASUREMENT"]191 OUT["Outcome<br/>━━━━━━━━━━<br/>Metric / endpoint"]192 end193194 subgraph Selection ["SELECTION/COLLIDERS"]195 COLL["Collider<br/>━━━━━━━━━━<br/>Post-treatment filter"]196 end197198 %% CAUSAL EDGES %%199 CONF -->|"confounds"| TREAT200 CONF -->|"confounds"| OUT201 INSTR -->|"causal"| TREAT202 TREAT -->|"causal"| MED203 MED -->|"mediates"| OUT204 TREAT -->|"selects"| COLL205 OUT -->|"selects"| COLL206207 %% CLASS ASSIGNMENTS %%208 class TREAT cli;209 class OUT output;210 class MED handler;211 class CONF stateNode;212 class COLL detector;213 class INSTR newComponent;214```215216**Color Legend:**217| Color | Category | Description |218|-------|----------|-------------|219| Dark Blue | Treatment | Treatment assignment variables |220| Dark Teal | Outcome | Outcome measurement variables |221| Orange | Mediator | Intermediate mechanism variables |222| Teal | Confounder | Shared causes of treatment and outcome |223| Red | Collider/Selection | Post-treatment filters (conditioning risk) |224| Green | Instrument | Variables affecting only treatment |225| Amber | Backdoor Path | Unblocked confounding path |226227## Identification Strategy228229| Assumption | Testable? | Evidence |230|------------|-----------|----------|231| {assumption} | {Yes/No} | {evidence from codebase} |232233## Unblocked Backdoor Paths234235| Path | Variables | Severity | Mitigation |236|------|-----------|----------|------------|237| {path} | {A -> ... -> B} | {High/Medium/Low} | {adjustment/unavailable} |238```239240---241242## Pre-Diagram Checklist243244Before creating the diagram, verify:245246- [ ] LOADED `/autoskillit:mermaid` skill using the Skill tool247- [ ] Using ONLY classDef styles from the mermaid skill (no invented colors)248- [ ] Diagram will include a color legend table249250---251252## Related Skills253254- `/autoskillit:make-experiment-diag` - Parent skill for lens selection255- `/autoskillit:mermaid` - MUST BE LOADED before creating diagram256- `/autoskillit:exp-lens-estimand-clarity` - For clarifying the target estimand257- `/autoskillit:exp-lens-validity-threats` - For broader validity threat inventory