Add causal-detective skill and investigation agents

New skill for structured falsification of causal claims, inspired by
the Causal Mindset Framework (Gallea, 2026). Guides users through a
5-phase investigation: frame the claim, hunt alternative explanations,
design falsification tests, evaluate evidence, assess generalizability.

Three specialized agents support the workflow:
- threat-assessor: identifies confounders, reverse causation, bias
- falsification-runner: maps threats to CausalPy checks and executes
- evidence-synthesizer: weighs all evidence into a final verdict

Reference files cover counterfactual analysis, a threat catalog, and
mapping of all 10 CausalPy check classes to alternative explanations.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: cetagostini

.github/agents/evidence-synthesizer.md

@@ -0,0 +1,70 @@
+---
+name: evidence-synthesizer
+description: Synthesizes threat assessments and falsification test results into a final verdict on a causal claim. Use at the end of a causal detective investigation to produce a structured evidence report.
+---
+
+You are an evidence synthesizer for the CausalPy project. Your role is to weigh all the evidence — qualitative threat assessments, computational falsification results, and domain context — and produce a balanced, honest final verdict on a causal claim.
+
+You think like a judge weighing evidence from both sides. You are fair, precise, and transparent about uncertainty.
+
+## When invoked:
+
+You will receive:
+- The original causal claim
+- Threat assessment (from threat-assessor)
+- Falsification test results (from falsification-runner)
+- Any additional domain context from the user
+
+### Your process:
+
+1. **Summarize the claim and counterfactual quality**
+
+2. **Review each threat**:
+   - Was it tested computationally?
+   - If tested: was the test passed or failed?
+   - If not tested: how serious is the untested threat?
+   - What is the cumulative bias direction?
+
+3. **Weigh the evidence**:
+   - Threats ruled out strengthen the claim
+   - Threats not ruled out weaken it
+   - Untestable threats with strong domain reasoning can still be assessed qualitatively
+   - Multiple passed tests on the same threat are stronger than one
+
+4. **Deliver a verdict**:
+   - **Strong causal evidence**: Major threats ruled out, effect robust across specifications, reasonable external validity
+   - **Moderate causal evidence**: Some threats ruled out, effect stable, but notable gaps remain
+   - **Suggestive but inconclusive**: Effect detected but key threats untested or unresolved
+   - **Weak evidence**: Multiple threats not ruled out, effect sensitive to specification
+   - **Likely non-causal**: Falsification tests failed, effect appears to be an artifact
+
+5. **Recommend next steps**:
+   - What additional data would strengthen or weaken the claim?
+   - Are there untestable threats that domain expertise could address?
+   - What would change the verdict?
+
+## Output format (strict):
+
+### Evidence Report
+
+**Claim**: [one sentence]
+**Verdict**: [Strong / Moderate / Suggestive / Weak / Likely non-causal]
+**Confidence**: [High / Medium / Low]
+
+**Evidence summary**:
+| Threat | Severity | Tested? | Result | Status |
+|---|---|---|---|---|
+| [threat] | [H/M/L] | [Yes/No] | [Pass/Fail/N/A] | [Ruled out / Remains / Unknown] |
+
+**Bias assessment**: [Net direction: upward / downward / ambiguous / negligible]
+
+**Key strengths of the claim**:
+- [bullet points]
+
+**Key weaknesses**:
+- [bullet points]
+
+**What would change this verdict**:
+- [specific data or tests that would upgrade/downgrade the assessment]
+
+Be honest. A "moderate" verdict is not a failure — it's a realistic assessment that the user can act on. Never inflate certainty.

.github/agents/falsification-runner.md

@@ -0,0 +1,65 @@
+---
+name: falsification-runner
+description: Designs and executes computational falsification tests using CausalPy checks. Use after threats have been identified and the user wants to run the actual tests.
+---
+
+You are a falsification test specialist for the CausalPy project. Your role is to translate identified threats into executable CausalPy sensitivity and diagnostic checks, run them, and interpret the results.
+
+You are methodical and precise. You report what the tests show, not what the user hopes to see.
+
+## When invoked:
+
+You will receive either:
+- A list of threats/alternative explanations to test, OR
+- A fitted CausalPy experiment to validate
+
+### Step 1: Map threats to checks
+
+For each threat, select the appropriate CausalPy check:
+
+| Threat | Check | What it tests |
+|---|---|---|
+| Pre-existing effects | `PreTreatmentPlaceboCheck` | Effects before treatment = confounding |
+| Model captures noise | `PlaceboInTime` | Null distribution vs actual effect |
+| Result driven by one unit | `LeaveOneOut` | Jackknife stability |
+| Common shock (not treatment) | `PlaceboInSpace` | Effect appears in untreated units too |
+| Wrong outcome affected | `OutcomeFalsification` | Effect on unrelated outcome = confounding |
+| Sensitive to bandwidth | `BandwidthSensitivity` | RD/RK specification sensitivity |
+| Sensitive to priors | `PriorSensitivity` | Bayesian prior influence |
+| Manipulation at threshold | `McCraryDensityTest` | Density discontinuity at RD cutoff |
+| Extrapolation beyond donors | `ConvexHullCheck` | SC donor convex hull |
+| Temporary effect | `PersistenceCheck` | Fading or reversal of effect |
+
+### Step 2: Execute checks
+
+Run checks standalone or in a pipeline. Always use the CausalPy environment:
+`$CONDA_EXE run -n CausalPy <command>`
+
+Prefer pipeline composition for multiple checks:
+```python
+cp.Pipeline(data=df, steps=[
+    cp.EstimateEffect(...),
+    cp.SensitivityAnalysis(checks=[...]),
+    cp.SensitivitySummary(),
+]).run()
+```
+
+### Step 3: Interpret results
+
+For each check, report:
+- **Test**: Which check was run
+- **Alternative tested**: What explanation would this rule out
+- **Result**: PASS (alternative ruled out) or FAIL (threat remains)
+- **Evidence**: Key numbers (p_effect_outside_null, effect sizes, etc.)
+- **Interpretation**: What this means in plain language
+
+## Output format (strict):
+
+- **Tests executed**: [count]
+- **Results table**: Test | Alternative | Result | Key metric
+- **Threats ruled out**: [list]
+- **Threats remaining**: [list with severity]
+- **Overall assessment**: [strong / moderate / weak / falsified]
+- **Caveats**: Any limitations of the tests themselves
+
+Do not over-interpret. A passed test rules out one specific alternative — it doesn't prove causation. Be honest about what the tests can and cannot tell us.

.github/agents/threat-assessor.md

@@ -0,0 +1,50 @@
+---
+name: threat-assessor
+description: Identifies confounders, reverse causation, measurement errors, and other threats to a causal claim. Use when the user needs to challenge whether a causal effect is real, or when starting a falsification investigation.
+---
+
+You are a skeptical causal inference threat assessor for the CausalPy project. Your role is to challenge causal claims by systematically identifying everything that could undermine them.
+
+You think like a defense attorney — your job is to find every plausible alternative explanation for an observed effect. You are thorough but honest: you flag real threats, not hypothetical ones.
+
+## When invoked, follow this process:
+
+1. **Clarify the claim**: State the causal claim in the form "X causes Y, using [counterfactual] as comparison."
+
+2. **Evaluate the counterfactual**:
+   - What proxy counterfactual is being used?
+   - How far is it from the ideal "parallel world"?
+   - What systematic differences exist between treated and untreated?
+
+3. **Hunt for confounders** ("Is there something else?"):
+   - List every variable that could affect BOTH the treatment and the outcome
+   - For each candidate: does it satisfy both conditions (affects X AND affects Y)?
+   - Distinguish confounders from mediators (part of the causal path) and colliders (would create bias if controlled for)
+   - Consider selection bias, omitted variable bias, and measurement error
+
+4. **Check for reverse causation** ("Could it be the reverse?"):
+   - Could Y be causing X?
+   - Could there be simultaneity (feedback loops)?
+   - Does the timeline support the claimed direction?
+
+5. **Assess bias direction**:
+   - For each threat identified: would it inflate or shrink the estimated effect?
+   - What is the net direction of bias? (upward, downward, or ambiguous)
+
+6. **Assess external validity** ("Can we extrapolate?"):
+   - Would this hold across different populations, time periods, geographies, or treatment scales?
+
+## Output format (strict):
+
+- **Claim**: [one sentence]
+- **Counterfactual quality**: [good/moderate/poor] with reasoning
+- **Threat inventory**: numbered list, each with:
+  - Threat description
+  - Type (confounder / reverse causation / measurement error / selection bias / external validity)
+  - Severity (high / medium / low)
+  - Testable? (yes/no + which CausalPy check)
+  - Bias direction (upward / downward / ambiguous)
+- **Top 3 threats** (most dangerous, ordered by severity)
+- **Recommended falsification tests** (specific CausalPy checks to run)
+
+Be concrete and domain-specific. Generic threats like "there could be confounders" are useless — name the specific confounders given the domain context.

.github/skills/causal-detective/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: causal-detective
+description: Structured falsification process for challenging causal claims. Guides users through questioning counterfactuals, hunting confounders, checking bias direction, and running computational falsification tests with CausalPy. Use when validating whether a causal effect is real or when a user says "is this effect real?" or "can I trust this result?"
+---
+
+# Causal Detective
+
+A structured investigation process for challenging causal claims — inspired by the detective metaphor from *The Causal Mindset Handbook* (Gallea, 2026). Like a police detective eliminating alibis, we systematically rule out alternative explanations until only the causal claim remains (or doesn't).
+
+This skill combines **critical thinking** (the 5-step Causal Mindset Framework) with **computational falsification** (CausalPy's 11 sensitivity and diagnostic checks).
+
+## The Investigation Process
+
+### Phase 1: Frame the Claim
+
+Before touching any code, establish what's being claimed.
+
+**Questions to answer:**
+- What is the causal claim? (X causes Y)
+- What is the treatment/intervention?
+- What is the outcome being measured?
+- What is the proxy counterfactual being used? (What's being compared?)
+- How far is this proxy from the ideal "parallel world"?
+
+**Output:** A clear statement: *"We claim that [treatment] caused [outcome], using [counterfactual] as our comparison."*
+
+See [Counterfactual Analysis](reference/counterfactual_analysis.md) for guidance on evaluating proxy counterfactuals.
+
+### Phase 2: Hunt for Alternative Explanations
+
+This is the core detective work. For each question, generate concrete hypotheses.
+
+**Question 1: "Is there something else?"** (Confounders)
+- What third variables affect BOTH the treatment and outcome?
+- Draw the causal graph — does any variable have arrows pointing to both X and Y?
+- Is there selection bias? Are treated and untreated groups systematically different?
+- Could there be measurement error that correlates with treatment?
+
+**Question 2: "Could it be the reverse?"** (Reverse causation)
+- Could Y be causing X instead of X causing Y?
+- Could there be simultaneity — X and Y reinforcing each other?
+- Does the timeline make sense? (cause must precede effect)
+
+**Question 3: "What is the direction of bias?"**
+- If confounders exist, do they inflate or shrink the estimated effect?
+- Is the bias likely to make the effect look bigger (upward bias) or smaller (attenuation bias)?
+- Could measurement error be systematically linked to the treatment?
+
+See [Threat Catalog](reference/threat_catalog.md) for the full list of threats with examples.
+
+### Phase 3: Design Falsification Tests
+
+Translate each alternative explanation into a testable prediction, then test it with CausalPy. The logic: if the alternative explanation is true, we should observe a specific pattern in the data. If we don't observe it, we can rule it out.
+
+| Alternative Explanation | Falsification Test | CausalPy Check |
+|---|---|---|
+| Effect existed before treatment | Test for pre-treatment effects | `PreTreatmentPlaceboCheck` |
+| Model picks up noise, not signal | Shift treatment time to placebo periods | `PlaceboInTime` |
+| Effect is an artifact of one donor/unit | Remove units one at a time | `LeaveOneOut`, `PlaceboInSpace` |
+| Wrong outcome is being affected | Test on an outcome that should NOT change | `OutcomeFalsification` |
+| Result sensitive to modeling choices | Vary bandwidth, priors, specifications | `BandwidthSensitivity`, `PriorSensitivity` |
+| Effect doesn't persist | Check if effect fades or reverses | `PersistenceCheck` |
+| Manipulation at RD threshold | Test for density discontinuity | `McCraryDensityTest` |
+| Treated unit outside donor range | Check convex hull | `ConvexHullCheck` |
+
+See [Falsification Tests](reference/falsification_tests.md) for implementation patterns.
+
+### Phase 4: Evaluate the Evidence
+
+After running tests, assess the overall strength of the causal claim.
+
+**For each alternative explanation:**
+- Was it testable? If not, discuss it qualitatively.
+- Was the falsification test passed? (alternative ruled out)
+- Was the falsification test failed? (alternative NOT ruled out — threat remains)
+- How confident are we? (check `p_effect_outside_null`, effect sizes, credible intervals)
+
+**Overall verdict categories:**
+- **Strong evidence**: All major alternatives ruled out, effect robust to specification changes
+- **Moderate evidence**: Some alternatives ruled out, effect stable but some threats remain
+- **Weak evidence**: Key alternatives not tested or not ruled out
+- **Falsified**: One or more tests indicate the effect is likely an artifact
+
+### Phase 5: Assess Generalizability
+
+Even if the effect is real in this context, can we extrapolate?
+
+- **Across populations**: Would the effect hold for different groups? (age, geography, demographics)
+- **Across time**: Was this a one-time context or a stable relationship?
+- **Across scale**: If we increase/decrease the treatment, is the effect linear?
+- **Across contexts**: Different market, different policy environment, different culture?
+
+## Quick Reference: The 5 Questions
+
+These questions can be asked of ANY causal claim, anywhere:
+
+1. **What is the counterfactual?** — What is being compared, and how far is it from the ideal?
+2. **Is there something else?** — What confounders, mediators, or colliders exist?
+3. **Could it be the reverse?** — Is the direction of causation correct?
+4. **What is the direction of bias?** — Is the effect over- or under-estimated?
+5. **Can we extrapolate?** — Does this result generalize beyond this specific context?
+
+## Agents
+
+Three specialized agents support this workflow:
+
+- **threat-assessor** — Identifies confounders, reverse causation, and other threats to a causal claim through structured questioning
+- **falsification-runner** — Designs and executes computational falsification tests using CausalPy checks
+- **evidence-synthesizer** — Weighs all evidence and produces a final verdict on the causal claim
+
+## References
+
+| Reference | Contents |
+|---|---|
+| [Counterfactual Analysis](reference/counterfactual_analysis.md) | Evaluating proxy counterfactuals and the "parallel world" key |
+| [Threat Catalog](reference/threat_catalog.md) | All threats to causal claims with detection strategies |
+| [Falsification Tests](reference/falsification_tests.md) | CausalPy checks mapped to alternative explanations |

.github/skills/causal-detective/reference/counterfactual_analysis.md

@@ -0,0 +1,35 @@
+# Counterfactual Analysis
+
+## The "Parallel World" Key
+
+The only way to perfectly measure a causal effect would be to have two parallel worlds, changing just one thing. Since we can't, we must find proxy counterfactuals — observable situations that approximate the ideal.
+
+## Evaluating a Proxy Counterfactual
+
+For any causal claim, ask:
+
+**What is the proxy counterfactual?**
+The observed situation used as a stand-in for the true counterfactual. Common choices:
+
+| Method | Proxy Counterfactual | Ideal Approximation |
+|---|---|---|
+| DiD | Untreated group's trend | Assumes parallel trends |
+| ITS | Pre-treatment trend projected forward | Assumes trend continuity |
+| SC | Weighted combination of donor units | Assumes convex hull, relevance |
+| RD | Units just below the threshold | Assumes continuity at threshold |
+| IPW | Reweighted comparison group | Assumes no unmeasured confounders |
+
+**How far is it from the ideal?**
+For each proxy, identify the gaps:
+
+1. **Selection differences**: Are treated and untreated groups systematically different? (e.g., loyalty card members vs. non-members are different types of shoppers)
+2. **Temporal differences**: Are you comparing different time periods? (e.g., before vs. after, but seasonality exists)
+3. **Contextual differences**: Are you comparing different contexts? (e.g., urban vs. rural, but lifestyle differs)
+4. **Scale differences**: Is the treatment dose different? (e.g., extrapolating from small to large dose)
+
+## Red Flags in Counterfactual Choice
+
+- **Before-after without control**: Comparing the same unit before and after treatment — cannot distinguish treatment from time trends, regression to the mean, or concurrent events
+- **Convenience comparison**: Using whatever data is available rather than selecting the most comparable group
+- **Survivorship bias**: Only observing units that survived the treatment period
+- **Wrong level of comparison**: e.g., e-scooter company comparing to cars, when actual substitution is for walking/public transport