causal-reasoning

Causal Reasoning

Causal Reasoning is an agent skill for testing causal claims and root-cause hypotheses without confusing correlation, plausibility, or source volume with identification.

It turns a causal question into a minimal model, researches the load-bearing arrows, compares credible rivals, actively seeks disconfirming evidence, and returns a conclusion capped by the weakest required link. Standard and Deep investigations can use a versioned, machine-checkable evidence ledger.

Why this exists

Most research workflows are good at collecting facts and weak at deciding what those facts can establish. A convincing story can still rest on confounding, reverse causality, selection, measurement error, dependent sources, or an unidentified counterfactual.

Causal Reasoning keeps three judgments separate:

• causal rung: association, intervention, counterfactual, or not identified;
• evidence confidence: high, moderate, low, or very low;
• arrow status: hypothesis, supported, contested, or rejected.

That separation makes the result legible to people and structured enough for agents to inspect, update, and audit.

How it works

flowchart LR
    Q["Falsifiable causal question"] --> M["Minimal causal model"]
    M --> V["Rank arrows by value of information"]
    V --> E["Confirming and disconfirming evidence"]
    E --> G["Grade identification and confidence separately"]
    G --> R["Compare rival models"]
    R --> C["Calibrated conclusion"]
    C --> A["Trust audit and next evidence"]
    E <--> L["Evidence ledger v2.0"]

The skill supports Rapid, Standard, and Deep modes. It chooses the lightest mode proportionate to the decision and stakes rather than forcing every question through an exhaustive report.

Good uses

• Does a policy or product change cause an observed outcome?
• What actually drove an engineering incident?
• Does the proposed mechanism survive credible alternatives?
• What evidence would prove or disprove a strategic thesis?
• Is a result associational, interventional, or counterfactual?
• Which unresolved link is most valuable to investigate next?

It is not intended for simple factual lookup, broad surveys without a causal claim, or routine troubleshooting that does not need evidence-backed causal inference.

Install

Requirements: Codex with plugin support and Python 3.10 or newer.

codex plugin marketplace add KMerdan/causal-reasoning
codex plugin add causal-reasoning@kmerdan-causal-reasoning

Start a new Codex task after installation so the skill is discovered.

To update later:

codex plugin marketplace upgrade kmerdan-causal-reasoning
codex plugin add causal-reasoning@kmerdan-causal-reasoning

Use

Natural-language examples:

Use $causal-reasoning to test whether this product change caused retention to improve.
Use $causal-reasoning to investigate the root cause of this incident and challenge the leading hypothesis.
Use $causal-reasoning to audit this causal thesis, compare rival models, and say what the evidence actually supports.

The skill infers the language, effort mode, and most useful output format. For consequential or disputed claims, specify the decision, population, intervention or exposure, outcome, and time window when you know them.

Evidence ledger

For Standard and Deep work, the skill can maintain a JSON ledger that connects every source to specific causal arrows and preserves identification assumptions, threats, rivals, uncertainty, and disconfirming evidence.

Copy the template and validate a completed ledger:

cp plugins/causal-reasoning/skills/causal-reasoning/assets/evidence-ledger-template.json evidence-ledger.json
python3 plugins/causal-reasoning/skills/causal-reasoning/scripts/validate_evidence_ledger.py evidence-ledger.json --strict

Use --allow-template only to validate the blank distributed template. Strict mode treats unresolved audit warnings as failures.

Repository layout

.agents/plugins/marketplace.json                 Public Codex marketplace
plugins/causal-reasoning/
├── .codex-plugin/plugin.json                   Plugin manifest
├── skills/causal-reasoning/
│   ├── SKILL.md                                Agent workflow and guardrails
│   ├── agents/openai.yaml                      Skill discovery metadata
│   ├── assets/evidence-ledger-template.json    Ledger v2.0 template
│   ├── references/                             Framework and domain guidance
│   └── scripts/validate_evidence_ledger.py     Standard-library validator
└── tests/                                      Contract and validator tests
tools/validate_repository.py                    Repository packaging checks

Development

The runtime has no third-party Python dependencies.

make check

See CONTRIBUTING.md for the project invariants and pull-request expectations. Report security issues through SECURITY.md.

Interpretation boundary

This skill improves the discipline, traceability, and calibration of causal analysis; it does not manufacture identification from inadequate evidence. High-stakes medical, legal, financial, policy, or safety decisions still require appropriate data access and qualified domain review.

Project status

Version 1.0.0 publishes the causal workflow, seven focused references, the evidence-ledger v2.0 contract, and its deterministic validator. Backward-incompatible changes to the ledger or validation behavior will use a major release.

License

MIT © 2026 Dr. Merdan Bay. See LICENSE.

Causal Reasoning is an independent open-source project and is not affiliated with or endorsed by OpenAI.