Improve user/agent facing skills (#929)

* Clarify user-facing CausalPy skills

Rename the method-selection and execution skills so agents can route causal-design work separately from experiment-running guidance, and expand the execution references with current experiment coverage and scale-aware prior guidance.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Fix agent-facing CausalPy skill examples

Clarify unsupported experiment outputs and make the expanded execution references less likely to send agents into runtime errors.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: drbenvincent

.cursor/commands/causalpy_estimators.md

@@ -1,4 +1,4 @@
 # Causal Estimators
 
-This command points to the `performing-causal-analysis` Skill in
-`causalpy/skills/performing-causal-analysis/` for estimation, summaries, and plots.
+This command points to the `running-causalpy-experiments` Skill in
+`causalpy/skills/running-causalpy-experiments/` for estimation, summaries, priors, and plots.

.cursor/commands/causalpy_methods.md

@@ -2,5 +2,5 @@
 
 This command points to Skills in `causalpy/skills/`:
 
-- `designing-experiments` for method selection
-- `performing-causal-analysis` for method usage and references
+- `choosing-causalpy-methods` for method selection
+- `running-causalpy-experiments` for method usage and references

.cursor/commands/causalpy_research.md

@@ -1,4 +1,4 @@
 # Causal Research
 
-This command points to the `designing-experiments` Skill in
-`causalpy/skills/designing-experiments/` for method selection guidance.
+This command points to the `choosing-causalpy-methods` Skill in
+`causalpy/skills/choosing-causalpy-methods/` for method selection guidance.

causalpy/skills/README.md

@@ -8,6 +8,6 @@ Developer-focused skills (environment setup, PR workflows, testing conventions,
 
 | Path | Purpose |
 |------|---------|
-| `designing-experiments/` | Choosing the right quasi-experimental method |
-| `performing-causal-analysis/` | Fitting models, estimating impacts, plotting results |
+| `choosing-causalpy-methods/` | Choosing the right CausalPy experiment class from a causal question and data structure |
+| `running-causalpy-experiments/` | Fitting chosen experiments, configuring models and priors, summarizing, plotting, and interpreting results |
 | `running-placebo-analysis/` | Placebo-in-time sensitivity checks |

causalpy/skills/choosing-causalpy-methods/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: choosing-causalpy-methods
+description: Choose the appropriate CausalPy experiment class from a causal question, data structure, treatment assignment, and identification assumptions. Use before writing analysis code when the method is not yet settled.
+---
+
+# Choosing CausalPy Methods
+
+Use this skill to translate a user's causal question into a CausalPy experiment choice. This is the design-intake skill, not the implementation skill. Once the method is chosen, hand off to `running-causalpy-experiments` for constructor details, model configuration, priors, summaries, plots, and interpretation.
+
+## Intake Checklist
+
+1. Restate the estimand: ATE, ATT, local threshold effect, treatment-on-treated over time, cumulative impact, or a policy/campaign lift.
+2. Identify the data shape: single time series, wide panel of units, long panel of unit-time rows, cross-section, or pre/post group data.
+3. Identify treatment assignment: known intervention time, staggered adoption, threshold/cutoff, kink, instrument, observed treatment with confounders, or treated unit plus donor pool.
+4. Check the identifying story: parallel trends, no anticipation, no manipulation at cutoff, valid instrument, overlap/positivity, convex hull/donor support, or trend continuity.
+5. Recommend one primary CausalPy experiment and any plausible alternatives, then explain the extra data or assumptions needed to choose among them.
+
+## Fast Routing
+
+- One treated time series, known intervention time, no donor pool: `InterruptedTimeSeries`.
+- Known level/slope changes in one time series, especially multiple interruptions: `PiecewiseITS`.
+- Treated and control groups observed before and after one intervention: `DifferenceInDifferences`.
+- Units adopt treatment at different times: `StaggeredDifferenceInDifferences`.
+- One or more treated units with multiple untreated donor units in wide panel format: `SyntheticControl`.
+- Synthetic-control setting where both unit weights and pre-period time weights are part of the design: `SyntheticDifferenceInDifferences`.
+- Panel regression or fixed-effects adjustment is the target rather than a named quasi-experimental design: `PanelRegression`.
+- Pretest/posttest nonequivalent groups with a baseline outcome: `PrePostNEGD`.
+- Treatment assigned by crossing a cutoff in a running variable: `RegressionDiscontinuity`.
+- Treatment intensity changes slope at a threshold rather than jumping in level: `RegressionKink`.
+- Treatment is endogenous but there is a credible instrument: `InstrumentalVariable`.
+- Observational binary treatment with measured confounders and overlap: `InversePropensityWeighting`.
+
+## Output Pattern
+
+When you use this skill, return:
+
+- Recommended method: name the CausalPy experiment class.
+- Why it fits: tie the recommendation to data shape, assignment mechanism, and estimand.
+- Required columns/data layout: list the minimal data structure needed.
+- Key assumptions: state what must be credible for a causal interpretation.
+- Main risks: name obvious failure modes or sensitivity checks.
+- Next step: route to `running-causalpy-experiments` and the relevant method reference.
+
+## References
+
+- [Experiment decision guide](reference/experiment_decision_guide.md)

causalpy/skills/choosing-causalpy-methods/reference/experiment_decision_guide.md

@@ -0,0 +1,42 @@
+# Experiment Decision Guide
+
+Use this guide when an agent needs to choose a CausalPy experiment before writing analysis code. Prefer the simplest design that matches the data-generating story and has defensible identification assumptions.
+
+## Time-Series Designs
+
+| Situation | CausalPy class | Data shape | Main assumption | Common alternative |
+|---|---|---|---|---|
+| One outcome series, one intervention time, forecast counterfactual from pre-period | `InterruptedTimeSeries` | DataFrame indexed by time or with a time column | Pre-intervention trend model remains valid absent treatment | `PiecewiseITS` when estimating explicit level/slope changes in the full series |
+| Known level or slope changes, possibly multiple interruptions | `PiecewiseITS` | Single time series with time variable used in `step()` / `ramp()` formula terms | Functional form captures untreated trend plus intervention changes | `InterruptedTimeSeries` when the goal is pre-period forecasting |
+| Treated series plus donor units measured over time | `SyntheticControl` | Wide panel, columns are units | Donor pool can reproduce treated pre-period and supports counterfactual | `SyntheticDifferenceInDifferences` when time weights are part of the design |
+| Synthetic-control setting with unit weights and pre-period time weights | `SyntheticDifferenceInDifferences` | Wide panel, columns are units | Weighted controls and weighted pre-periods provide a credible counterfactual | `SyntheticControl` for simpler donor-weight-only analysis |
+
+## Panel And Group Designs
+
+| Situation | CausalPy class | Data shape | Main assumption | Common alternative |
+|---|---|---|---|---|
+| One treated group and one control group before/after treatment | `DifferenceInDifferences` | Long panel or repeated group-time observations with treatment and post indicators | Parallel trends between treated and control groups | `StaggeredDifferenceInDifferences` for staggered adoption |
+| Units adopt treatment at different times | `StaggeredDifferenceInDifferences` | Long unit-time panel with treatment timing | Parallel trends, no anticipation, absorbing treatment | `PanelRegression` for fixed-effects association or simpler adjustment |
+| Fixed-effects regression is the analysis target | `PanelRegression` | Long panel with unit identifiers and optional time identifiers | Fixed effects control relevant unit/time confounding | DiD variants when treatment timing is central |
+| Treated/control groups with baseline and post outcome | `PrePostNEGD` | Cross-sectional or group data with pre and post outcomes | Baseline outcome adjustment captures pre-existing group differences | `DifferenceInDifferences` when repeated observations over time are available |
+
+## Threshold And Cross-Sectional Designs
+
+| Situation | CausalPy class | Data shape | Main assumption | Common alternative |
+|---|---|---|---|---|
+| Treatment switches at a cutoff in a running variable | `RegressionDiscontinuity` | Cross-section or repeated observations with running variable and threshold | Units near cutoff are comparable and cannot precisely manipulate assignment | `RegressionKink` when slope changes rather than treatment level |
+| Treatment intensity changes slope at a threshold | `RegressionKink` | Cross-section or repeated observations with running variable and kink point | Smooth potential outcomes around the kink absent treatment-intensity change | `RegressionDiscontinuity` for jump discontinuities |
+| Endogenous treatment with valid instrument | `InstrumentalVariable` | DataFrame for outcome/treatment covariates plus instruments | Instrument relevance, exclusion, and no unblocked instrument-outcome path | `InversePropensityWeighting` if treatment is confounded but not instrumented |
+| Observed binary treatment with measured confounders | `InversePropensityWeighting` | Cross-section or panel rows with treatment, outcome, and confounders | Conditional exchangeability and overlap/positivity | Outcome regression or doubly robust workflows when available |
+
+## Method Selection Questions
+
+- Is treatment assigned by time, by unit, by threshold, by instrument, or by observed covariates?
+- Is the estimand a total post-period impact, an event-study path, a local threshold effect, or an adjusted treatment contrast?
+- Are controls actual untreated units, donor time series, never-treated cohorts, or measured covariates?
+- Does the data have enough pre-treatment history to support trend, donor, or placebo checks?
+- Is the assignment mechanism credible enough for causal language, or should the agent frame the result as descriptive?
+
+## Handoff To Execution
+
+After selecting a method, use `running-causalpy-experiments` for the concrete workflow: data preparation, constructor arguments, model choice, scale-aware priors, summaries, plots, effect summaries, and sensitivity checks.