Skip to main content

Documentation Index

Fetch the complete documentation index at: https://wuweism.com/llms.txt

Use this file to discover all available pages before exploring further.

Counterfactual reasoning asks a question that standard data analysis cannot answer: what would have happened if things had been different? Not “what pattern exists in the data” (Rung 1), not “what would happen if we intervene going forward” (Rung 2), but “given what actually occurred, what would the outcome have been under a different scenario?” This is Rung 3 of Pearl’s causal ladder — the most powerful, and the most demanding, form of causal inference.

​
What a counterfactual question looks like

Counterfactual questions are recognizable by their hypothetical structure. They refer to specific realized events and ask about unrealized alternatives:
  • “Would this patient have recovered if they had received the treatment earlier?”
  • “Would the defendant’s injury have occurred but for the manufacturer’s negligence?”
  • “Would the neural circuit have activated if the inhibitory signal had been absent?”
These questions cannot be answered from observational data alone. They require knowing the underlying causal mechanisms well enough to run the system forward under a modified condition.

​
Do-calculus interventions — the do(·) operator

The formal tool for counterfactual and interventional reasoning is Pearl’s do-calculus. The notation do(X = v) means: set variable X to the value v, regardless of what would naturally have caused X to take that value. This is different from conditioning. Conditioning on X = v means “look at observations where X happened to equal v.” The do(·) operator cuts X free from its natural causes in the causal graph and forces it to a specific value — simulating a perfect experimental intervention. 
Conditioning:   P(Y | X = v)        — among cases where X = v, what is Y?
Intervention:   P(Y | do(X = v))    — if we forced X = v, what would Y be?
Counterfactual: P(Yₓ = v | X = v') — given X was v', what would Y have been if X had been v?
In Wu-Weism, you trigger an intervention by switching to intervene operator mode in the Causal Workbench and framing your question with explicit intervention language — for example, “What would have happened if the dosage had been doubled?”

​
The Identifiability Gate

Before Wu-Weism computes a counterfactual or intervention, it runs an Identifiability Gate — a check that determines whether the causal effect can be validly estimated from the available information. An effect is identifiable if every backdoor path from the treatment variable to the outcome variable can be blocked by adjusting for observable variables in the causal graph. If unobserved confounders exist and cannot be controlled for, the effect is not identifiable, and a spurious estimate would be misleading. The identifiability check requires:
  • The treatment variable — the variable you are intervening on
  • The outcome variable — the variable you are measuring
  • The adjustment set — the variables to condition on to block backdoor paths
  • The known confounders — variables that causally influence both treatment and outcome
The check returns a structured result: 
interface IdentifiabilityResult {
  identifiable: boolean;
  requiredConfounders: string[];
  adjustmentSet: string[];
  missingConfounders: string[];
  note: string;
}
If identifiable is false, the missingConfounders field lists the variables that would need to be observed to make the effect estimable. The note explains the specific identifiability failure in plain language.

​
What happens when an intervention is blocked

If the Identifiability Gate determines that a causal effect cannot be identified, Wu-Weism does not generate a Rung 2 or Rung 3 answer. Instead:
  1. The response is downgraded to Rung 1 — an association-level answer based on the available observational data.
  2. The response includes a clear explanation of why the intervention could not be computed, naming the missing confounders.
  3. The Claim Ledger records the downgrade decision as part of the claim’s provenance.
A downgraded response is not a failure — it is an honest answer. An unidentifiable causal effect estimate would be invalid regardless of how confident it appeared. The Identifiability Gate prevents you from drawing causal conclusions from data that cannot support them.

​
Counterfactual traces

Every intervention that passes the Identifiability Gate produces a counterfactual trace — a deterministic, persistent record of the computation. Traces exist so that analyses can be audited, reproduced, and challenged. A counterfactual trace contains: 
interface CounterfactualQueryResult {
  estimand: string;
  actualOutcome: number;
  counterfactualOutcome: number;
  difference: number;
  explanation: string;
}
FieldDescription
estimandThe formal causal estimand — what quantity was computed
actualOutcomeThe observed outcome in the actual world
counterfactualOutcomeThe estimated outcome under the hypothetical intervention
differenceThe estimated causal effect: counterfactualOutcome − actualOutcome
explanationA plain-language account of how the counterfactual was computed
In addition to the result, each trace record includes:
Trace metadata fieldDescription
modelKeyThe SCM used for the computation
versionThe version of the SCM
intervention.variableThe variable that was intervened on
intervention.valueThe value it was set to
methodThe computation method — always deterministic_graph_diff
traceIdThe unique identifier for this trace
assumptionsThe modelling assumptions under which the result holds
adjustmentSetThe variables conditioned on to identify the effect
The deterministic_graph_diff method works by: (1) abducing the exogenous noise variables consistent with the observed outcome, (2) modifying the intervened variable in the causal graph, (3) propagating the change forward through the graph to produce the counterfactual outcome. The difference between the two outcomes is the estimated causal effect.

​
Viewing counterfactual traces

Traces are accessible via the API using the trace ID, which is displayed in the workbench alongside any Rung 3 response. 
GET /api/scm/counterfactual-traces/{traceId}
This returns the full trace record — result, metadata, assumptions, and adjustment set. You can also find the trace ID associated with a specific claim in the Claim Ledger. If a claim has claim_kind: "counterfactual", its trace_id field points to the trace that produced it.
Counterfactual traces are immutable once written. The trace you retrieve today will be identical to the trace recorded at the time of computation — making them suitable as audit records for legal or regulatory purposes.

​
How to trigger an intervention in the workbench

1

Open the Causal Workbench

Navigate to the Causal Chat surface in the workbench.
2

Switch to intervene mode

Select the intervene operator from the mode selector in the chat input area. The interface will shift to indicate you are framing an intervention, not an observation query.
3

Frame your question as an intervention

State what variable you are setting and to what value. Use explicit language: “What would the outcome have been if [variable] had been [value]?”Wu-Weism will parse the intervention target and value from your question. If ambiguous, it will ask for clarification before running the identifiability check.
4

Review the identifiability check

The workbench shows the result of the Identifiability Gate before generating the answer. If the check fails, you will see which confounders are missing and why the effect cannot be estimated.
5

Receive the counterfactual answer

If the check passes, Wu-Weism computes the counterfactual and returns a Rung 3 response with the actual outcome, counterfactual outcome, estimated difference, and the trace ID. The trace is written to the ledger immediately.

​
Worked example

Suppose you are analyzing the effect of an educational intervention — specifically, whether earlier introduction of a learning strategy caused better outcomes. Your question (intervene mode): “What would the student’s test score have been if the intervention had begun in week 1 rather than week 6?” What Wu-Weism does:
  1. Classifies the domain as education.
  2. Loads the education SCM from the registry.
  3. Checks identifiability: Is the causal effect of intervention timing on test scores identifiable, given available confounders (prior attainment, engagement, teacher quality)?
  4. If identifiable: Computes the counterfactual outcome by setting intervention_start_week = 1 in the causal graph and propagating forward.
  5. Returns the actual score, the counterfactual score, the estimated difference, and the trace ID.
The trace record includes:
  • estimand: P(score | do(intervention_start_week = 1))
  • actualOutcome: 72 (observed score with week 6 start)
  • counterfactualOutcome: 81 (estimated score with week 1 start)
  • difference: +9
  • adjustmentSet: ["prior_attainment", "engagement_score"]
Counterfactuals are only as reliable as the SCM they are computed from. If the causal graph is misspecified — if important variables are missing, or if the functional relationships between variables are wrong — the counterfactual outcome will be wrong too.Wu-Weism mitigates this through the Identifiability Gate (which detects missing confounders) and through the assumptions field in the trace record (which makes the modelling assumptions explicit). But the SCM is always a model of reality, not reality itself.
Yes. Each intervention creates a separate trace. You can run multiple counterfactuals for the same session, varying the intervention variable, the intervention value, or both. Each trace is independent and carries its own identifiability result.
A Rung 2 answer estimates the population-level causal effect of an intervention: “If we assigned treatment X to everyone, what would the average outcome be?” A Rung 3 answer addresses a specific realized case: “Given that this individual had outcome Y, what would their outcome have been if they had received treatment X instead?”Rung 3 requires knowing the exogenous factors specific to the individual case — which is why it is both more powerful and more demanding than Rung 2.

​
Related concepts

Pearl's causal ladder

Where counterfactuals sit in the three-rung hierarchy.

Structural Causal Models

The models that make counterfactual computation possible.

Claim Ledger

How counterfactual claims are recorded and audited.