The Econometrics tool runs econometric estimation and saves reproducible result artifacts for killstata.

Use it after the dataset has been imported, cleaned, and QA-checked.

Execution policy:
- For non-trivial econometric work, plan internally before calling tools.
- Keep user-facing text concise and report-like; do not narrate every intermediate read, verifier step, or retry unless the user explicitly asks for details.
- The default stage order is: plan -> healthcheck/import -> preprocess/qa -> baseline estimate -> diagnostics -> robustness -> grounded narrative.
- After a failure, inspect the reflection metadata and rerun only the failed stage.
- If QA or diagnostics produce blocking_errors, stop and repair the failed stage before continuing.
- Warnings may continue, but they must be disclosed in the narrative and final reporting.
- If the user asks for a reasonable baseline, a standard baseline, or asks the tool to choose the baseline without naming a concrete estimator, use `smart_baseline`.
- If the user asks for method recommendation only and does not want execution yet, use `auto_recommend`.
- If the user explicitly names a concrete estimator, keep that estimator unless it is not executable with the available variables or identifiers.
- If an explicitly requested estimator is not executable, rescue to `smart_baseline` or the closest executable baseline and disclose the original request, the failure reason, and the executed method.

Working-format policy:
- Read canonical dataset stages through datasetId/stageId whenever available
- Canonical working datasets are Parquet stages
- Excel / CSV / DTA are source or delivery formats, not the primary estimation layer
- `.killstata/` is the internal project workspace; it is not the main user-facing delivery folder
- Successful econometric runs publish user-facing files into `killstata_output_YYYYMMDD_HHMM` in the source data file's directory, with `_02`, `_03`, ... added automatically for same-minute collisions
- The delivery bundle rule applies to both canonical `datasetId/stageId` runs and direct `dataPath` runs

## Supported Methods

Core baseline methods:
- auto_recommend: inspect dataset structure, infer candidate variable roles, and recommend a baseline econometric path
- smart_baseline: run auto_recommend first, convert the recommendation into an executable baseline, estimate it, run diagnostics, and preserve downgrade decisions
- panel_fe_regression: two-way fixed-effects panel regression with clustered standard errors
- baseline_regression: alias of the panel FE baseline path
- ols_regression: cross-sectional or pooled OLS

Causal inference methods:
- did_static
- did_staggered
- did_event_study
- did_event_study_viz
- iv_2sls
- iv_test
- psm_construction
- psm_matching
- psm_ipw
- psm_regression
- psm_double_robust
- psm_dr_ipw_ra
- psm_visualize
- rdd_sharp
- rdd_fuzzy
- rdd_fuzzy_global

## Key Parameters

- methodName: the econometric method name
- dataPath: dataset path; optional when datasetId/stageId is provided
- datasetId, stageId: canonical Parquet stage reference; prefer this after import
- runId: optional run identifier; reuse the same runId to publish outputs under one workflow folder
- branch: analysis branch name for saved outputs
- dependentVar: dependent variable column name; optional only for `auto_recommend`, but strongly recommended there as well
- treatmentVar: key explanatory or treatment variable column name when required
- covariates: control variable column names
- entityVar: panel entity identifier for panel_fe_regression / baseline_regression
- timeVar: panel time identifier for panel_fe_regression / baseline_regression
- clusterVar: clustering variable for standard errors; defaults to entityVar for panel FE
- options: method-specific options such as placebo_var and alternative_specifications
- outputDir: directory for saved outputs

## Output Contract

For panel_fe_regression and baseline_regression, the tool saves:
- `results.json`
- `coefficient_table.csv`
- `coefficient_table.xlsx`
- `three_line_table.md`
- `three_line_table.tex`
- `three_line_table.xlsx`
- `three_line_table.docx`
- `diagnostics.json`
- `model_metadata.json`
- `narrative.md`
- `model_summary.txt`
- `numeric_snapshot.json`
- `delivery_result_summary.md`
- `result_report.docx` for the baseline panel FE delivery path

For other regression-capable methods, the tool also saves:
- `results.json`
- `coefficient_table.csv` when coefficient output exists
- `coefficient_table.xlsx` when coefficient output exists
- `three_line_table.md` / `.tex` / `.xlsx` / `.docx` when a non-empty coefficient table is available
- `diagnostics.json`
- `model_metadata.json`
- `narrative.md`
- `model_summary.txt`
- `numeric_snapshot.json` when grounded regression output is available

For `auto_recommend`, the tool saves:
- `profile.json`
- `recommendation.json`
- `results.json`
- `narrative.md`

For `smart_baseline`, the tool saves the recommendation artifacts above and then continues to save the executed baseline regression artifacts in the same run folder.

Front-end delivery rule:
- `auto_recommend` does not have to create a `killstata_output_*` bundle when it only emits recommendations
- Any successful estimation run with formal result artifacts must create a `killstata_output_*` delivery bundle
- A completed econometric analysis delivery bundle must contain exactly four default user-facing files:
  - `回归结果_<method>.md`
  - `三线表_<method>.tex`
  - `三线表_<method>.docx`
  - `计量分析数据_<method>.xlsx`
- Do not generate `期刊小论文_<method>.docx` by default
- If the regression result is significant at a conventional level, ask the user whether to generate `期刊小论文_<method>.docx`
- Only generate and publish `期刊小论文_<method>.docx` after explicit user confirmation, for example with `options.generateJournalPaper=true`
- Extra diagnostics, metadata, snapshots, CSV files, raw result JSON, and auxiliary tables stay in `.killstata`

The `auto_recommend` path should:
- infer whether the dataset is closer to cross-section, time series, panel, or repeated cross-section
- identify likely entity, time, treatment, and instrument candidates
- recommend a baseline method family such as OLS, panel FE, DID-family follow-up, IV/2SLS, or double-robust follow-up
- recommend a covariance strategy such as nonrobust, robust, cluster, or HAC
- emit post-estimation downgrade rules such as switching to robust SE after failed heteroskedasticity diagnostics

The `smart_baseline` path should:
- run `auto_recommend`
- choose the best executable baseline implied by the recommendation
- fall back when the recommended family is not executable with the currently available variables
- run the concrete baseline estimate
- carry forward downgrade traces such as `did_static -> panel_fe_regression`, `panel_fe_regression -> pooled_ols`, or `nonrobust -> HC1`

Diagnostics follow a three-part structure:
- `core`
  - heteroskedasticity tests
  - multicollinearity / VIF
  - condition number
  - residual normality / autocorrelation
  - influence summary
  - balance/common-support checks when relevant
- `robustness`
  - alternative covariance checks
  - leave-one-cluster-out when applicable
  - placebo checks when specified
  - alternative specification checks when specified
- `qa`
  - warnings
  - blocking_errors
  - suggested_repairs
  - panel / clustering integrity metadata when relevant

Grounding contract:
- Statistical claims must come from `numeric_snapshot.json` or grounded tool metadata.
- Do not report coefficients, p-values, standard errors, R-squared, N, descriptive statistics, or correlations without a numeric snapshot.

## Example Usage

Two-way fixed-effects baseline regression on a canonical Parquet stage:
{
  "methodName": "panel_fe_regression",
  "datasetId": "did_dataset_xxxxxx",
  "stageId": "stage_000",
  "dependentVar": "经济发展水平",
  "treatmentVar": "did",
  "entityVar": "地区",
  "timeVar": "year",
  "clusterVar": "地区"
}

## Validation Guidance

- Run `data_import` with action="qa" before panel estimation
- For unclear datasets, run `auto_recommend` first to inspect structure and baseline method suggestions
- When the user asks for the tool to choose and run the baseline automatically, use `smart_baseline`
- When the user explicitly names a method, do not route through `smart_baseline` unless the requested method is not executable
- If you rescue from an explicit method to another baseline, say so clearly in the final narrative
- If the source was Excel/CSV/DTA, import it first and estimate from the returned Parquet stage
- Read `diagnostics.json` after the baseline model and before drawing conclusions
- Run robustness checks after core diagnostics when the design requires them
- Read `numeric_snapshot.json` before reporting any statistical number in natural language
- Use explicit column names
- Read `diagnostics.json` and `model_metadata.json` after estimation
- If the tool returns warnings or blocking errors, repair the data/specification and rerun only the failed stage

## Planning And Skill Guidance

- Before spreadsheet-heavy or table-heavy workflows, load `workflow-orchestrator` first, then the most relevant specialist skill.
- Prefer project-local skills under `.killstata/skills` when the same skill exists at multiple tiers.
- If no project-local override exists, prefer user-installed skills before `builtin`.
- Prefer installed skill aliases rather than inventing names:
  - Excel/XLSX processing -> `xlsx-processor`
  - Descriptive profiling -> `descriptive-analysis`
  - DID -> `did-estimation`
  - IV -> `iv-estimation`
  - PSM -> `psm-estimation`
  - RDD -> `rdd-estimation`
  - Diagnostic testing / robustness -> `robustness-check` or `regression-reporting`
- Prefer explicit methodName, explicit identifiers, explicit clustering choice, and explicit options over implicit defaults.
