From 2d682a56c3ddc95abfb7274a0d631e95bedf8c3c Mon Sep 17 00:00:00 2001 From: pedrohcgs Date: Wed, 20 May 2026 11:43:20 -0400 Subject: [PATCH] =?UTF-8?q?feat(v1.9.0=20Pass=204):=20Stata=20expansion=20?= =?UTF-8?q?=E2=80=94=20stata-mcp=20+=20/stata-replication=20+=20audit-repr?= =?UTF-8?q?oducibility?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit User-driven expansion to support Stata-first projects. Correction to plan: AEA does not mandate Stata — the expansion targets users whose pipelines are Stata-first for audience reach or original- replication-package fidelity. Three sub-items: 4.1 — stata-mcp integration. New ecosystem subsection in guide/workflow-guide.qmd documents SepineTam/stata-mcp (171 stars, v1.17.3, May 2026): install via `claude mcp add stata-mcp --scope user -- uvx stata-mcp`. New TROUBLESHOOTING entry covers the "stata-mcp not registered" pre- flight failure with install steps + verification. 4.2 — New skill /stata-replication. Mirrors /data-analysis for R- first projects. Scaffolds numbered .do pipeline (00_install.do through 99_run_all.do), executes via stata-mcp, outputs land in scripts/stata/_outputs/. --from-r flag ports R pipelines with optional cross-check. Phase 0 halts if MCP server not registered. 4.2 — New rule .claude/rules/stata-code-conventions.md. Path-scoped on **/*.do and scripts/stata/**. Codifies header (version 18, clear all, set seed/sortseed, log capture); numbered pipeline; outputs convention with sessionInfo.txt; esttab for publication-ready tables; significance stars convention; clustering discipline (reghdfe, cluster bootstrap < 50 groups); balance via iebaltab; AEA Data Editor compliance checklist; Stata-trap table. 4.3 — /audit-reproducibility source-language coverage extended. New "Source-language coverage" section documents R / Stata / Python ecosystems with read-output methods (haven::read_dta, pyreadstat). Stata-specific notes: esttab .tex as strongest provenance signal under \input{} pattern; clustering-df diagnosis for reghdfe vs reg, cluster(). On-disk inventory: 36 skills / 16 agents / 26 rules / 6 hooks (was 35/16/25/6 after Pass 3B). +1 skill (/stata-replication), +1 rule (stata-code-conventions). Verification: - check-surface-sync.sh: 26/26 pass, counts 36/16/26/6 - check-skill-integrity: pass on new SKILL.md - quarto render: clean - quality_score: 100/100 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- .claude/rules/stata-code-conventions.md | 179 ++++++++++++++++++ .claude/skills/audit-reproducibility/SKILL.md | 18 +- .claude/skills/stata-replication/SKILL.md | 117 ++++++++++++ CHANGELOG.md | 37 ++++ CLAUDE.md | 1 + README.md | 2 +- TROUBLESHOOTING.md | 12 ++ docs/index.html | 4 +- docs/workflow-guide.html | 42 ++-- guide/workflow-guide.html | 42 ++-- guide/workflow-guide.qmd | 19 +- templates/skill-template.md | 2 +- 12 files changed, 443 insertions(+), 32 deletions(-) create mode 100644 .claude/rules/stata-code-conventions.md create mode 100644 .claude/skills/stata-replication/SKILL.md diff --git a/.claude/rules/stata-code-conventions.md b/.claude/rules/stata-code-conventions.md new file mode 100644 index 000000000..6b2cd6bb5 --- /dev/null +++ b/.claude/rules/stata-code-conventions.md @@ -0,0 +1,179 @@ +--- +paths: + - "**/*.do" + - "scripts/stata/**" +--- + +# Stata Code Conventions + +**Reproducibility is the default, not a feature.** A `.do` file should be runnable from a clean shell with no manual intervention. Every script ends in the same state regardless of how many times it runs. + +> This rule mirrors [`r-code-conventions.md`](r-code-conventions.md) for users whose pipelines are Stata-first. Forkers who use both R and Stata in the same project: both rules apply on their respective files. + +## 1. Reproducibility scaffolding + +Every `.do` file starts with the same header: + +```stata +/*------------------------------------------------------------ +File: NN_descriptive_name.do +Purpose: [one-sentence description] +Inputs: [path to inputs] +Outputs: [path to outputs] +Run order: Standalone | After NN_prior.do +------------------------------------------------------------*/ + +version 18 // pin Stata semantics +clear all +set more off +set seed 12345 // pin RNG seed for any random ops +set sortseed 12345 // pin sort stability across versions +cap log close +cap log close _all // belt-and-suspenders +log using "scripts/stata/_outputs/NN_log.smcl", replace +``` + +Why each line: + +- **`version 18`** — explicit semantics. New Stata versions can silently change defaults (e.g., `reghdfe` clustering df-adjustment); pinning is the only defence. +- **`clear all`** — no leftover state from a prior session. +- **`set more off`** — scripts shouldn't pause for keystrokes. +- **`set seed` + `set sortseed`** — every random op + every `sort` is deterministic. +- **`cap log close _all`** — pre-emptively close any logs the previous session left open. +- **`log using ... , replace`** — capture stdout; `replace` ensures re-runs don't append. + +End every `.do` file with: + +```stata +log close +exit, clear STATA // explicit clean exit; useful in batch mode +``` + +## 2. Numbered pipeline + +Scripts live in `scripts/stata/` and are numbered for run order: + +``` +scripts/stata/ +├── 00_install.do # ssc install packages, set globals, paths +├── 01_clean.do # raw → cleaned panel +├── 02_descriptive.do # summary tables, balance, attrition +├── 03_analyze.do # main regression specs +├── 04_robustness.do # alt specs, sensitivity +├── 05_tables_figures.do # estout/esttab + graph export +└── 99_run_all.do # do "01_clean.do" / do "02_..." / ... +``` + +The 99-script is the **one-command reproduction**: `do scripts/stata/99_run_all.do` from the repo root produces every output the paper cites. AEA Data Editor checks this exact shape. + +## 3. Outputs convention + +All outputs land in `scripts/stata/_outputs/`: + +``` +scripts/stata/_outputs/ +├── 01_log.smcl # captured stdout per script +├── clean_panel.dta # cleaned data +├── descriptives.csv # summary stats +├── main_results.tex # esttab → .tex for direct \input{} in paper +├── balance_table.tex +├── fig_eventstudy.pdf # graph export, vector +└── sessionInfo.txt # capture stata version + installed pkg versions +``` + +`sessionInfo.txt` is mandatory. Generate via: + +```stata +* At end of 00_install.do (or via a dedicated sessioninfo subroutine): +log using "scripts/stata/_outputs/sessionInfo.txt", text replace +which estout +which reghdfe +which ivreg2 +about +log close +``` + +This gives the AEA / referee / future-you the package versions actually used. + +## 4. Tables (estout / esttab) + +Use `esttab` for any table that appears in the paper. **Never hand-format a table in LaTeX** — the `\input{}` pattern means the table cell values come from the actual estimation: + +```stata +quietly: reghdfe y x1 x2, absorb(unit time) cluster(unit) +eststo m1 +quietly: reghdfe y x1 x2 controls, absorb(unit time) cluster(unit) +eststo m2 + +esttab m1 m2 using "scripts/stata/_outputs/tab_main.tex", replace /// + booktabs label /// use the variable labels you set + se(2) b(3) /// SE in parens, 3-decimal coeffs + star(* 0.10 ** 0.05 *** 0.01) /// significance convention + stats(N r2, fmt(%9.0fc %9.3f) labels("Observations" "R²")) /// + nonotes addnote("Robust SEs clustered at unit level.") +``` + +Then in the manuscript: `\input{scripts/stata/_outputs/tab_main.tex}` — table values update mechanically every time the .do file runs. + +## 5. Significance-stars convention + +The default is `* 0.10 ** 0.05 *** 0.01` (the econ convention; matches AER / QJE / JPE / ECMA defaults). Political science journals (APSR / AJPS / JOP) often use the same. Document the convention in the table note even though it's "obvious" — referees read the notes. + +For one-tailed contexts (rare in published work), use `* 0.05 ** 0.025 *** 0.005` and explain why in the note. Default to two-tailed. + +## 6. Clustering and SE conventions + +- **Always cluster at the level of treatment assignment** (or the highest plausible level of dependence). Never use default `, robust` without justification. +- **`reghdfe` defaults to df-adjusted clustering** but check — Stata's `, cluster()` and `reghdfe ... , cluster()` use different df adjustments in some edge cases. The version pin at top of file is partial defence; explicit `, dofadj() ` is the rest. +- **Bootstrap clustering** for very small clusters (< 50 groups): use `cluster bootstrap` not `bootstrap, cluster()`. + +## 7. Balance / attrition discipline + +For every RCT or quasi-experimental design: + +- **Balance table** via `iebaltab` (World Bank `ietoolkit` package). Don't reinvent. +- **Attrition table** — fraction missing per round, balanced by treatment status. Same `iebaltab` invocation with different outcome. +- **Manipulation checks** (survey experiments) — pass rate per arm. Document in the paper, not just the .do. + +## 8. Figures (graph export) + +```stata +graph export "scripts/stata/_outputs/fig_eventstudy.pdf", replace as(pdf) +graph export "scripts/stata/_outputs/fig_eventstudy.png", replace as(png) width(2000) +``` + +Both vector (PDF for the paper) and raster (PNG for slides). Don't rely on the auto-generated `.gph` — it's not portable across Stata versions. + +## 9. Common Stata → R / Stata → AEA traps + +| Trap | Fix | +|---|---| +| `reg y x, cluster(id)` without explicit df-adjustment | Use `reghdfe` for explicit df; document the adjustment in the table note | +| Bootstrap reps inconsistent across runs | `set seed` + `set sortseed` at top of file; use `bootstrap, reps(N) seed(X)` | +| `replace` modifying observed data | Always `gen new_var = ... ` and inspect before `drop` | +| `merge 1:1` without `assert` | `merge 1:1 id using foo, assert(3)` — fail loud on mismatched keys | +| `if` on missing values | Stata treats `.` as `+∞` in inequality comparisons. `if x > 5 & x != .` for non-missing-and-greater-than-5 | +| `egen sum(x)` deprecated | `egen total(x)` is the modern form; `egen sum()` still works but `bysort id: egen y = total(x)` is the safer pattern | + +## 10. AEA Data Editor compliance + +The [AEA Data Editor checklist](https://aeadataeditor.github.io/) requires: + +- `README.md` at repo root describing data source, computational requirements, run instructions. +- A single command that reproduces all results (`do scripts/stata/99_run_all.do`). +- All scripts numbered and ordered. +- A separate `requirements.txt`-equivalent — for Stata, that's the `sessionInfo.txt` from §3 plus a list of `ssc install` commands in `00_install.do`. +- License (MIT / GPL / similar). +- No hard-coded paths — use globals or relative paths from repo root. + +## Enforcement + +- [`/stata-replication`](../skills/stata-replication/SKILL.md) is the analogue of `/data-analysis` for Stata. It emits .do files conforming to this convention. +- [`/audit-reproducibility`](../skills/audit-reproducibility/SKILL.md) handles Stata `.dta` outputs alongside R `.rds` (via `haven` or `pyreadstat`). +- [`/review-r`](../skills/review-r/SKILL.md) is R-specific; a Stata-equivalent is on the v1.9-backlog. + +## Cross-references + +- [`r-code-conventions.md`](r-code-conventions.md) — analogous discipline for R-first pipelines. +- [`replication-protocol.md`](replication-protocol.md) — tolerance contract that applies across R / Stata / Python. +- [stata-mcp on GitHub](https://github.com/SepineTam/stata-mcp) — the MCP server that lets Claude Code execute Stata `.do` files. Install via `claude mcp add stata-mcp --scope user -- uvx stata-mcp`. diff --git a/.claude/skills/audit-reproducibility/SKILL.md b/.claude/skills/audit-reproducibility/SKILL.md index a003977ff..ff28ad65c 100644 --- a/.claude/skills/audit-reproducibility/SKILL.md +++ b/.claude/skills/audit-reproducibility/SKILL.md @@ -22,7 +22,7 @@ Compare numeric claims in a manuscript (point estimates, standard errors, p-valu ## Inputs - `$0` — path to the manuscript (`.tex`, `.qmd`, `.md`, `.pdf`). Required. -- `$1` — path to the outputs directory. Defaults to `scripts/R/_outputs/`. Can be `_targets/objects/`, a Stata `.do`-file log directory, etc. +- `$1` — path to the outputs directory. Defaults to `scripts/R/_outputs/`. Recognised alternatives: `scripts/stata/_outputs/` (Stata pipelines built by [`/stata-replication`](../stata-replication/SKILL.md)), `_targets/objects/` (R `targets` workflows), any directory the user-specified outputs live in. ## Workflow @@ -153,6 +153,22 @@ Write `quality_reports/reproducibility_audit_[manuscript-name].md`: - **Any FAIL:** exit 1, summary printed to stderr. This makes the skill usable as a `/commit` pre-commit gate — see `replication-protocol.md` for the enforcement pattern. - **UNMATCHED > 0 (with 0 FAIL):** exit 0 with warning — user must manually review. +## Source-language coverage + +The skill compares manuscript claims against outputs in three source-language ecosystems: + +| Source | Default outputs dir | Read-output via | Common claim sources | +|---|---|---|---| +| **R** (default) | `scripts/R/_outputs/` | `readRDS()`, `arrow::read_parquet()`, `vroom::vroom()` | `.rds` / `.parquet` / `.csv` / `tinytable` `.tex` | +| **Stata** (v1.9.0) | `scripts/stata/_outputs/` | `haven::read_dta()` from R, or `pyreadstat.read_dta()` from Python | `.dta` / `esttab` `.tex` / `.smcl` log values | +| **Python** | `scripts/python/_outputs/` (or `_targets/`) | `pandas.read_parquet`, `pickle.load` | `.parquet` / `.pickle` / `.csv` | + +**Stata-specific notes (v1.9.0):** + +- `.dta` outputs are read via `haven::read_dta()` (R), `pyreadstat.read_dta()` (Python), or by parsing the corresponding `esttab` `.tex` if the table-cell value is what the manuscript cites. +- Manuscript cell `\input{scripts/stata/_outputs/tab_main.tex}` is the strongest provenance signal — the cell value comes mechanically from the .do file. Match the location in the `.tex` to the regression call in `03_analyze.do`. +- Clustering df adjustments can differ between `reghdfe` and base `reg, cluster()`. If a SE mismatches at the 2nd decimal, the tolerance in `replication-protocol.md` covers it; if it mismatches at the 1st decimal, investigate the df adjustment. + ## Passport-mode (v1.9.0) When `quality_reports/passports/.yaml` exists, the skill operates in **passport mode**: instead of emitting a one-shot report, it **reads, updates, and rewrites** the passport file in place. diff --git a/.claude/skills/stata-replication/SKILL.md b/.claude/skills/stata-replication/SKILL.md new file mode 100644 index 000000000..bcaa49764 --- /dev/null +++ b/.claude/skills/stata-replication/SKILL.md @@ -0,0 +1,117 @@ +--- +name: stata-replication +description: End-to-end Stata replication pipeline — scaffolds numbered `.do` files in `scripts/stata/`, executes them via the `stata-mcp` MCP server, captures logs and outputs to `scripts/stata/_outputs/`, and produces publication-ready tables (esttab) and figures (graph export). Mirrors `/data-analysis` for R-first projects. Use when user says "stata replication", "set up Stata pipeline", "scaffold the .do files", "run Stata analysis", "AEA replication package in Stata", or when a project's analysis language is Stata not R. +author: Claude Code Academic Workflow +version: 1.0.0 +argument-hint: "[paper-or-data-pointer] [--from-r] [--no-execute]" +disable-model-invocation: true +allowed-tools: ["Read", "Write", "Edit", "Glob", "Grep", "Bash", "Task"] +--- + +# `/stata-replication` — Stata pipeline scaffold + execution + +Build a complete Stata replication pipeline in `scripts/stata/`: numbered `.do` files following [`.claude/rules/stata-code-conventions.md`](../../rules/stata-code-conventions.md), executed via the [`stata-mcp`](https://github.com/SepineTam/stata-mcp) MCP server, with outputs landing in `scripts/stata/_outputs/`. + +## When to use + +- Your project's analysis language is **Stata** (not R). Common in econ field experiments, RCT studies, and any AEA submission where the original replication package is Stata. +- You're porting an R-first project to Stata for an AEA submission. +- You're adding a Stata robustness check to an R-first paper. +- You want a one-command reproduction: `do scripts/stata/99_run_all.do`. + +## When NOT to use + +- Your project is R-first. Use [`/data-analysis`](../data-analysis/SKILL.md). +- Your project is Python-first. Neither this skill nor `/data-analysis` is the right fit; consider extending the convention rule for Python or porting one of these skills. +- You're doing quick exploratory work. The numbered-pipeline scaffold is for replication packages, not scratch notebooks. + +## Prerequisite: `stata-mcp` installed + +This skill requires the `stata-mcp` MCP server. Install once per user: + +```bash +claude mcp add stata-mcp --scope user -- uvx stata-mcp +``` + +The MCP server provides command-guarded Stata execution (refuses destructive operations like `!/shell/erase`), RAM monitoring, and Stata Language Server pairing. Maintained by SepineTam, 171 stars on GitHub as of 2026-05. + +If `stata-mcp` is not installed, the skill halts at Phase 0 with installation instructions. + +## Workflow + +### Phase 0: Pre-flight + +1. Verify `stata-mcp` is registered in the user's MCP configuration. If not → halt with install instructions. +2. Verify Stata is installed locally (the MCP server cannot run without it). Output stata version to confirm. +3. Confirm `scripts/stata/` directory exists or can be created. +4. Read [`.claude/rules/stata-code-conventions.md`](../../rules/stata-code-conventions.md) — every emitted `.do` file follows this convention. +5. If `--from-r` flag is set, locate the existing R pipeline at `scripts/R/` and use it as a translation source. Apply the Stata → R pitfalls table from `replication-protocol.md` in reverse. + +### Phase 1: Scaffold the pipeline + +Emit (or update) these files in `scripts/stata/`, each conforming to the header convention from `stata-code-conventions.md`: + +``` +scripts/stata/ +├── 00_install.do # ssc install, set globals, paths, sessionInfo capture +├── 01_clean.do # raw → cleaned panel +├── 02_descriptive.do # summary tables, balance (iebaltab), attrition +├── 03_analyze.do # main regression specs (reghdfe / ivreg2 as needed) +├── 04_robustness.do # alt specs, sensitivity +├── 05_tables_figures.do # esttab .tex outputs + graph export PDFs +└── 99_run_all.do # do "01_clean.do" / do "02_..." / ... +``` + +If the paper or data source suggests specific specs (e.g., DiD with `reghdfe`, IV with `ivreg2`, RD with `rdrobust`), tailor `03_analyze.do` accordingly. + +### Phase 2: Execute (unless `--no-execute`) + +For each script in numbered order: + +1. Dispatch to `stata-mcp` to execute the `.do` file. +2. Capture the log (Stata writes to `scripts/stata/_outputs/NN_log.smcl` per the header convention) and the resulting `.dta` / `.tex` / `.pdf` outputs. +3. If a script fails, halt — do NOT auto-fix unless the failure is trivial (typo flagged by Stata at parse time). For substantive failures (insufficient observations, singular matrices, missing covariates), surface to the user. + +For long-running scripts (> 2 minutes), use the **Monitor tool** to stream stdout — same pattern documented in `/data-analysis` and `/audit-reproducibility`. + +### Phase 3: Verify + +1. Confirm every expected output exists in `scripts/stata/_outputs/`. +2. Check `sessionInfo.txt` was captured (package versions). +3. Run `/audit-reproducibility` if a manuscript exists — it now handles Stata `.dta` outputs via `haven`/`pyreadstat` (Pass 4.3). +4. Report scripts run, outputs produced, any warnings from Stata. + +### Phase 4 (optional): R cross-check + +If `--from-r` was set, run the R version of the same analysis (assumed to live at `scripts/R/`) and compare: + +- Point estimates: should match to ~0.01 (per `replication-protocol.md` tolerance). +- Standard errors: should match to ~0.05 (clustering df adjustments can differ slightly between Stata and R). +- Sample sizes: must match exactly. + +Discrepancies are surfaced for the user to investigate — typical culprits: clustering df, default options (logit vs probit for PS), bootstrap seed handling. + +## Companion skills + +- [`/data-analysis`](../data-analysis/SKILL.md) — R analogue. Same pipeline shape, different language. +- [`/audit-reproducibility`](../audit-reproducibility/SKILL.md) — reads both `.rds` and `.dta` outputs. Cross-checks manuscript claims against the produced values. Updated in v1.9.0 to handle Stata outputs. +- [`/review-paper`](../review-paper/SKILL.md) — if the paper exists and cites tables/figures produced by this pipeline, `/review-paper` auto-invokes `/audit-reproducibility` (per `cross-artifact-review.md`). + +## Anti-patterns + +- **Hand-editing `.dta` files.** Never. All transformations happen via the `.do` files; `.dta` outputs are derived and reproducible. +- **Skipping the `99_run_all.do`.** This is the AEA-mandated one-command entry point. Build it even for small projects. +- **Using `, robust` by default.** Use `, cluster(id)` at the appropriate level — see `stata-code-conventions.md` §6. +- **Hand-formatting tables in LaTeX.** Use `esttab` and `\input{}` — see `stata-code-conventions.md` §4. +- **Pinning Stata version in only one .do file.** Every `.do` file starts with `version 18` per the convention. + +## Cross-references + +- [`.claude/rules/stata-code-conventions.md`](../../rules/stata-code-conventions.md) — the discipline contract. +- [`.claude/rules/replication-protocol.md`](../../rules/replication-protocol.md) — tolerance thresholds (applies across R / Stata / Python). +- [stata-mcp on GitHub](https://github.com/SepineTam/stata-mcp) — the MCP server this skill depends on. +- [AEA Data Editor checklist](https://aeadataeditor.github.io/) — replication-package standards. + +## Long-running fits / batch reruns: use the Monitor tool (Apr 2026) + +Long Stata fits (multi-hour bootstrap with `cluster bootstrap`, large `reghdfe` with millions of observations, simulation studies) should be background-launched and tailed with the Monitor tool — same pattern as `/data-analysis` and `/audit-reproducibility` for R / Python. The .do file logs to SMCL; the Monitor tool follows stderr so Claude can react to errors mid-stream. diff --git a/CHANGELOG.md b/CHANGELOG.md index af11ca4d4..021917edb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -220,6 +220,43 @@ Three additions to the cost-discipline and memory-management lenses: - `quarto render guide/workflow-guide.qmd` — clean render - `python3 scripts/quality_score.py guide/workflow-guide.qmd` — 100/100 [EXCELLENCE] +### Pass 4 — Stata expansion: stata-mcp + `/stata-replication` + audit-reproducibility extension (2026-05-20) + +User-driven expansion of the template to support Stata-first projects (correction to the original v1.9.0 plan: AEA does not *mandate* Stata; the expansion targets users whose pipelines are Stata-first for reasons of audience reach or original-replication-package fidelity). Three sub-items: + +#### Added — new skill + +- **`.claude/skills/stata-replication/`** — `/stata-replication [paper-or-data]` scaffolds a numbered Stata pipeline (`00_install.do` through `99_run_all.do`) in `scripts/stata/` and executes via the [`stata-mcp`](https://github.com/SepineTam/stata-mcp) MCP server. Mirrors `/data-analysis` for R-first projects. `--from-r` flag ports an existing R pipeline. `--no-execute` produces scaffolding only. Phase 0 pre-flight halts if `stata-mcp` is not registered (with install instructions); Phase 4 (optional) runs R cross-check on `--from-r` translations to surface clustering-df / default-option drift. + +#### Added — new rule + +- **`.claude/rules/stata-code-conventions.md`** — path-scoped on `**/*.do` and `scripts/stata/**`. Codifies: standard header (`version 18`, `clear all`, `set seed`, `set sortseed`, `cap log close`, log capture); numbered pipeline (00–99); outputs convention (`scripts/stata/_outputs/` with `sessionInfo.txt`); `esttab` for publication-ready tables with `\input{}` mechanical-update pattern; significance-stars convention (`* 0.10 ** 0.05 *** 0.01`); clustering / SE discipline (`reghdfe`, cluster bootstrap for < 50 groups); balance + attrition via `iebaltab`; graph export to vector + raster; AEA Data Editor compliance checklist. Common Stata-to-R-or-AEA traps table. + +#### Changed — `/audit-reproducibility` source-language coverage + +- **`.claude/skills/audit-reproducibility/SKILL.md`** — new "Source-language coverage" section documents the three supported ecosystems (R / Stata / Python) with default outputs directories and read-output method per language. Stata-specific notes added: `.dta` outputs read via `haven::read_dta()` (R) or `pyreadstat.read_dta()` (Python); `esttab` `.tex` table-cell values as strongest provenance signal when manuscript uses `\input{}`; clustering-df discrepancy diagnosis (`reghdfe` vs `reg, cluster()`). + +#### Added — TROUBLESHOOTING entry + +- **`TROUBLESHOOTING.md`** — new "/stata-replication halts at 'stata-mcp not registered'" section. Documents the one-command install (`claude mcp add stata-mcp --scope user -- uvx stata-mcp`), the `uv` prerequisite, and the verify step (`claude mcp list`). + +#### Added — Ecosystem entry + +- **`guide/workflow-guide.qmd` Ecosystem section** — new "stata-mcp: MCP server for Stata execution" subsection (before ClaudeCodeTools). Documents SepineTam's project, install command, why it matters for v1.9.0's Stata expansion, and the parallel-skill relationship between `/data-analysis` (R) and `/stata-replication` (Stata). + +#### Changed — count-bearing surfaces + +- **Inventory:** **36 skills, 16 agents, 26 rules, 6 hooks** (was 35 / 16 / 25 / 6 after Pass 3B). All 6 count-bearing surfaces updated. Note: rules count rises only by 1 (the Stata convention rule); skills count rises only by 1 (`/stata-replication` itself); agents unchanged. +- **`CLAUDE.md` Skills Quick Reference** — added `/stata-replication` row. +- **Guide Appendix** — added `/stata-replication` row to All Skills, `Stata Code Conventions` row to path-scoped All Rules. + +#### Verification — Pass 4 + +- `./scripts/check-surface-sync.sh` — 26/26 assertions pass; counts now **36 / 16 / 26 / 6** +- `./scripts/check-skill-integrity.py` — all checks pass on the new SKILL.md +- `quarto render guide/workflow-guide.qmd` — clean render +- `python3 scripts/quality_score.py guide/workflow-guide.qmd` — 100/100 [EXCELLENCE] + --- ## v1.8.0 — 2026-04-27 diff --git a/CLAUDE.md b/CLAUDE.md index d5a28b4ec..29acc0dde 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -121,6 +121,7 @@ Enforced by `/commit` (halts + asks for override); not enforced by a git pre-com | `/prompt-only [text] [depth] [--save path]` | Same formatting as `/prompt`, but emits the prompt as a reusable artifact (no execution) | | `/compress-session [slug]` | Distil current session into structured notes before auto-compaction (vs `/checkpoint` for natural stops) | | `/promote-memory [filter]` | Five-critic council that votes on which `[LEARN]` entries graduate from personal-memory.md to MEMORY.md | +| `/stata-replication [paper-or-data]` | End-to-end Stata pipeline scaffold + execution via `stata-mcp` (mirrors `/data-analysis` for R) | --- diff --git a/README.md b/README.md index e48a9e743..4fb29982c 100644 --- a/README.md +++ b/README.md @@ -152,7 +152,7 @@ The guide covers Claude Code's latest capabilities: ## What's Included
-16 agents, 35 skills, 25 rules, 6 hooks (click to expand) +16 agents, 36 skills, 26 rules, 6 hooks (click to expand) ### Agents (`.claude/agents/`) diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index 3f216aad3..50448eeea 100644 --- a/TROUBLESHOOTING.md +++ b/TROUBLESHOOTING.md @@ -20,6 +20,18 @@ Install Quarto from [quarto.org/docs/get-started](https://quarto.org/docs/get-st Required by `/extract-tikz`. `brew install pdf2svg` (macOS) / `apt install pdf2svg` (Debian/Ubuntu) / `dnf install pdf2svg` (Fedora). +### `/stata-replication` halts at "stata-mcp not registered" + +The Stata pipeline skill needs the [`stata-mcp`](https://github.com/SepineTam/stata-mcp) MCP server. Install once per user: + +```bash +claude mcp add stata-mcp --scope user -- uvx stata-mcp +``` + +`uvx` is the `uv` package runner (`brew install uv` if missing). The MCP server requires a local Stata installation — it's a bridge, not a replacement. Once installed, restart your Claude Code session so the MCP server registers. + +Verify with `claude mcp list` — `stata-mcp` should appear with status `connected`. The skill also halts if Stata itself is not on `PATH`; the install instructions documented in [`/stata-replication`](/.claude/skills/stata-replication/SKILL.md) Phase 0 cover both pre-flight checks. + ### Claude keeps asking permission for every tool Default permission mode prompts on every `Bash`, `Edit`, `Write`. Two fixes: diff --git a/docs/index.html b/docs/index.html index 89b7da3a7..204ada4b5 100644 --- a/docs/index.html +++ b/docs/index.html @@ -12,7 +12,7 @@ - + @@ -209,7 +209,7 @@

What's in the template

  • 14 specialized agents — proofreader, slide auditor, pedagogy reviewer, R reviewer, TikZ critic, domain reviewer, adversarial QA pair, translator, verifier, claim-verifier (Chain-of-Verification), plus simulated-peer-review trio (editor, domain referee, methods referee)
  • Adversarial critic-fixer loop — two agents that check each other's work across up to 5 rounds — the critic can't fix, the fixer can't approve
  • Quality scoring with mandatory verification — every file scored 0–100; /commit halts below 80 (user can override with an explicit reason); skills that implement the orchestrator pattern verify every output before reporting done
    • -
  • 35 slash commands + 25 context-aware rules — /compile-latex, /proofread, /deploy, /commit, /qa-quarto, /lit-review, /review-paper, /respond-to-referees, /new-diagram, /data-analysis, /audit-reproducibility, /checkpoint, /preregister, and more — plus quality gates, TikZ prevention/measurement, notation consistency, and R conventions
    • +
  • 36 slash commands + 26 context-aware rules — /compile-latex, /proofread, /deploy, /commit, /qa-quarto, /lit-review, /review-paper, /respond-to-referees, /new-diagram, /data-analysis, /audit-reproducibility, /checkpoint, /preregister, and more — plus quality gates, TikZ prevention/measurement, notation consistency, and R conventions
  • Simulated peer review — /review-paper --peer <journal> runs a full editorial pipeline: editor desk review, two blind referees with deliberately different dispositions (STRUCTURAL / CREDIBILITY / MEASUREMENT / POLICY / THEORY / SKEPTIC), editorial synthesis with FATAL / ADDRESSABLE / TASTE classification. Calibrated to 5 econ journals (AER / QJE / JPE / ECMA / ReStud) plus a template for adding your own field. Adapted from Hugo Sant’Anna’s clo-author with permission.
  • Research workflow skills — /lit-review for literature synthesis, /research-ideation for hypothesis generation, /interview-me to formalize ideas, /review-paper for manuscript review, /data-analysis for end-to-end R analysis
  • Smart hooks — Desktop notifications (macOS/Linux), pre-compaction context snapshots to session logs, progressive context-usage warnings, post-edit verify reminders
    • diff --git a/docs/workflow-guide.html b/docs/workflow-guide.html index fed6a1aaf..1b5866970 100644 --- a/docs/workflow-guide.html +++ b/docs/workflow-guide.html @@ -2477,9 +2477,10 @@

    Table of contents

  • 6.4 MixtapeTools: The Rhetoric of Decks
  • 6.5 AEA Data Editor Template
  • 6.6 autoresearch: Constraint-Based Autonomous Research
    • -
  • 6.7 ClaudeCodeTools: The Editor Persona
    • -
  • 6.8 Anthropic-Shipped Apr 2026 Utilities
    • -
  • 6.9 Community Adoption
    • +
  • 6.7 stata-mcp: MCP server for Stata execution
    • +
  • 6.8 ClaudeCodeTools: The Editor Persona
    • +
  • 6.9 Anthropic-Shipped Apr 2026 Utilities
    • +
  • 6.10 Community Adoption
  • 7 Customizing for Your Domain
      @@ -2755,7 +2756,7 @@

      -

      You talk, Claude orchestrates. The 16 agents, 35 skills, and 25 rules exist so you don’t have to think about them. Describe your goal, approve the plan, and let the system work.

      +

      You talk, Claude orchestrates. The 16 agents, 36 skills, and 26 rules exist so you don’t have to think about them. Describe your goal, approve the plan, and let the system work.

      @@ -2768,7 +2769,7 @@

      -

      This guide describes the full system — 16 agents, 35 skills, 25 rules. That is the ceiling, not the floor. Start with just CLAUDE.md and 2–3 skills (/compile-latex, /proofread, /commit). Add rules and agents as you discover what you need. The template is designed for progressive adoption: fork it, fill in the placeholders, and start working. Everything else is there when you’re ready.

      +

      This guide describes the full system — 16 agents, 36 skills, 26 rules. That is the ceiling, not the floor. Start with just CLAUDE.md and 2–3 skills (/compile-latex, /proofread, /commit). Add rules and agents as you discover what you need. The template is designed for progressive adoption: fork it, fill in the placeholders, and start working. Everything else is there when you’re ready.

      @@ -3531,7 +3532,7 @@

      -

      Claude Code ships with built-in skills beyond this template’s 35: /batch orchestrates parallel refactoring across your codebase (using git worktrees for isolation), /simplify runs 3-agent code review and applies fixes, and /debug helps troubleshoot sessions. These complement the academic skills above.

      +

      Claude Code ships with built-in skills beyond this template’s 36: /batch orchestrates parallel refactoring across your codebase (using git worktrees for isolation), /simplify runs 3-agent code review and applies fixes, and /debug helps troubleshoot sessions. These complement the academic skills above.

      @@ -6008,8 +6009,15 @@

      ## Success Metric RMSE of ATT estimate. Lower is better. Report coverage rate alongside. -
      -

      6.7 ClaudeCodeTools: The Editor Persona

      +
      +

      6.7 stata-mcp: MCP server for Stata execution

      +

      Repository: SepineTam/stata-mcp Author: SepineTam (171+ stars, 91 releases, v1.17.3 as of May 2026)

      +

      A mature MCP server that lets Claude Code execute Stata .do files via a command-guarded interface — refuses destructive shell ops (!/shell/erase etc.), monitors RAM, and pairs with the Stata Language Server. Install once per user: claude mcp add stata-mcp --scope user -- uvx stata-mcp (requires uv and a local Stata install).

      +

      Why it matters for this template: v1.9.0 added /stata-replication for Stata-first projects, which depends on this MCP server. R-first projects (the original template focus) continue to use /data-analysis; the two skills are parallel — same pipeline shape, different source language. AEA submissions where the original replication package is in Stata are the canonical use case.

      +

      For end-to-end Stata workflows, see .claude/rules/stata-code-conventions.md (header scaffold, numbered pipeline, esttab tables, clustering discipline, AEA Data Editor compliance).

      +
      +
      +

      6.8 ClaudeCodeTools: The Editor Persona

      Repository: aspi6246/ClaudeCodeTools

      A collection of Claude Code personas, including “The Editor” — a deeply structured academic paper reviewer that runs seven sequential audit passes (see Pattern 15). Notable features:

        @@ -6019,8 +6027,8 @@

        -

        6.8 Anthropic-Shipped Apr 2026 Utilities

        +
        +

        6.9 Anthropic-Shipped Apr 2026 Utilities

        These are first-party Claude Code commands you can invoke directly without forking anything. Worth knowing because they fill gaps this template intentionally doesn’t try to fill:

        • /team-onboarding (Week 15) — packages your local Claude Code setup (CLAUDE.md, skills, agents, hooks, settings) into a replayable guide. Useful for lab groups: a PI configures the workflow once, the rest of the lab runs /team-onboarding and inherits a working copy. Complements but doesn’t replace this template’s “fork + customize” model.
          • @@ -6034,8 +6042,8 @@

          -

          6.9 Community Adoption

          +
          +

          6.10 Community Adoption

          As of March 2026, 15+ research groups across multiple disciplines have forked and adapted this workflow for their own projects:

          • Economics — China innovation policy, mental health and layoffs, AIGC and stock prices, capital/labor shares in healthcare
            • @@ -6711,6 +6719,11 @@

          @@ -6873,6 +6886,11 @@

          +Stata Code Conventions +stata-code-conventions.md +**/*.do, scripts/stata/** — header scaffold, numbered pipeline, esttab tables, clustering discipline, AEA compliance (v1.9.0) +

        diff --git a/guide/workflow-guide.html b/guide/workflow-guide.html index fed6a1aaf..1b5866970 100644 --- a/guide/workflow-guide.html +++ b/guide/workflow-guide.html @@ -2477,9 +2477,10 @@

        Table of contents

      • 6.4 MixtapeTools: The Rhetoric of Decks
      • 6.5 AEA Data Editor Template
      • 6.6 autoresearch: Constraint-Based Autonomous Research
        • -
      • 6.7 ClaudeCodeTools: The Editor Persona
        • -
      • 6.8 Anthropic-Shipped Apr 2026 Utilities
        • -
      • 6.9 Community Adoption
        • +
      • 6.7 stata-mcp: MCP server for Stata execution
        • +
      • 6.8 ClaudeCodeTools: The Editor Persona
        • +
      • 6.9 Anthropic-Shipped Apr 2026 Utilities
        • +
      • 6.10 Community Adoption
    • 7 Customizing for Your Domain
        @@ -2755,7 +2756,7 @@

        -

        You talk, Claude orchestrates. The 16 agents, 35 skills, and 25 rules exist so you don’t have to think about them. Describe your goal, approve the plan, and let the system work.

        +

        You talk, Claude orchestrates. The 16 agents, 36 skills, and 26 rules exist so you don’t have to think about them. Describe your goal, approve the plan, and let the system work.

        @@ -2768,7 +2769,7 @@

        -

        This guide describes the full system — 16 agents, 35 skills, 25 rules. That is the ceiling, not the floor. Start with just CLAUDE.md and 2–3 skills (/compile-latex, /proofread, /commit). Add rules and agents as you discover what you need. The template is designed for progressive adoption: fork it, fill in the placeholders, and start working. Everything else is there when you’re ready.

        +

        This guide describes the full system — 16 agents, 36 skills, 26 rules. That is the ceiling, not the floor. Start with just CLAUDE.md and 2–3 skills (/compile-latex, /proofread, /commit). Add rules and agents as you discover what you need. The template is designed for progressive adoption: fork it, fill in the placeholders, and start working. Everything else is there when you’re ready.

        @@ -3531,7 +3532,7 @@

        -

        Claude Code ships with built-in skills beyond this template’s 35: /batch orchestrates parallel refactoring across your codebase (using git worktrees for isolation), /simplify runs 3-agent code review and applies fixes, and /debug helps troubleshoot sessions. These complement the academic skills above.

        +

        Claude Code ships with built-in skills beyond this template’s 36: /batch orchestrates parallel refactoring across your codebase (using git worktrees for isolation), /simplify runs 3-agent code review and applies fixes, and /debug helps troubleshoot sessions. These complement the academic skills above.

      • @@ -6008,8 +6009,15 @@

      ## Success Metric RMSE of ATT estimate. Lower is better. Report coverage rate alongside.

      -
      -

      6.7 ClaudeCodeTools: The Editor Persona

      +
      +

      6.7 stata-mcp: MCP server for Stata execution

      +

      Repository: SepineTam/stata-mcp Author: SepineTam (171+ stars, 91 releases, v1.17.3 as of May 2026)

      +

      A mature MCP server that lets Claude Code execute Stata .do files via a command-guarded interface — refuses destructive shell ops (!/shell/erase etc.), monitors RAM, and pairs with the Stata Language Server. Install once per user: claude mcp add stata-mcp --scope user -- uvx stata-mcp (requires uv and a local Stata install).

      +

      Why it matters for this template: v1.9.0 added /stata-replication for Stata-first projects, which depends on this MCP server. R-first projects (the original template focus) continue to use /data-analysis; the two skills are parallel — same pipeline shape, different source language. AEA submissions where the original replication package is in Stata are the canonical use case.

      +

      For end-to-end Stata workflows, see .claude/rules/stata-code-conventions.md (header scaffold, numbered pipeline, esttab tables, clustering discipline, AEA Data Editor compliance).

      +
      +
      +

      6.8 ClaudeCodeTools: The Editor Persona

      Repository: aspi6246/ClaudeCodeTools

      A collection of Claude Code personas, including “The Editor” — a deeply structured academic paper reviewer that runs seven sequential audit passes (see Pattern 15). Notable features:

        @@ -6019,8 +6027,8 @@

        -

        6.8 Anthropic-Shipped Apr 2026 Utilities

        +
        +

        6.9 Anthropic-Shipped Apr 2026 Utilities

        These are first-party Claude Code commands you can invoke directly without forking anything. Worth knowing because they fill gaps this template intentionally doesn’t try to fill:

        • /team-onboarding (Week 15) — packages your local Claude Code setup (CLAUDE.md, skills, agents, hooks, settings) into a replayable guide. Useful for lab groups: a PI configures the workflow once, the rest of the lab runs /team-onboarding and inherits a working copy. Complements but doesn’t replace this template’s “fork + customize” model.
          • @@ -6034,8 +6042,8 @@

          -

          6.9 Community Adoption

          +
          +

          6.10 Community Adoption

          As of March 2026, 15+ research groups across multiple disciplines have forked and adapted this workflow for their own projects:

          • Economics — China innovation policy, mental health and layoffs, AIGC and stock prices, capital/labor shares in healthcare
            • @@ -6711,6 +6719,11 @@

          @@ -6873,6 +6886,11 @@

          +Stata Code Conventions +stata-code-conventions.md +**/*.do, scripts/stata/** — header scaffold, numbered pipeline, esttab tables, clustering discipline, AEA compliance (v1.9.0) +

        diff --git a/guide/workflow-guide.qmd b/guide/workflow-guide.qmd index 52212d502..10ad3870f 100644 --- a/guide/workflow-guide.qmd +++ b/guide/workflow-guide.qmd @@ -155,13 +155,13 @@ Most of the time, you just describe what you want and Claude handles the rest. E ::: {.callout-important} ## The Bottom Line -**You talk, Claude orchestrates.** The 16 agents, 35 skills, and 25 rules exist so you don't have to think about them. Describe your goal, approve the plan, and let the system work. +**You talk, Claude orchestrates.** The 16 agents, 36 skills, and 26 rules exist so you don't have to think about them. Describe your goal, approve the plan, and let the system work. ::: ::: {.callout-note} ## You Don't Need All of This on Day One -This guide describes the full system --- 16 agents, 35 skills, 25 rules. That is the ceiling, not the floor. **Start with just CLAUDE.md and 2--3 skills** (`/compile-latex`, `/proofread`, `/commit`). Add rules and agents as you discover what you need. The template is designed for progressive adoption: fork it, fill in the placeholders, and start working. Everything else is there when you're ready. +This guide describes the full system --- 16 agents, 36 skills, 26 rules. That is the ceiling, not the floor. **Start with just CLAUDE.md and 2--3 skills** (`/compile-latex`, `/proofread`, `/commit`). Add rules and agents as you discover what you need. The template is designed for progressive adoption: fork it, fill in the placeholders, and start working. Everything else is there when you're ready. ::: --- @@ -665,7 +665,7 @@ argument-hint: "[filename without .tex extension]" ::: {.callout-note} ## Built-In Skills -Claude Code ships with built-in skills beyond this template's 35: `/batch` orchestrates parallel refactoring across your codebase (using git worktrees for isolation), `/simplify` runs 3-agent code review and applies fixes, and `/debug` helps troubleshoot sessions. These complement the academic skills above. +Claude Code ships with built-in skills beyond this template's 36: `/batch` orchestrates parallel refactoring across your codebase (using git worktrees for isolation), `/simplify` runs 3-agent code review and applies fixes, and `/debug` helps troubleshoot sessions. These complement the academic skills above. ::: ## Agents --- Specialized Reviewers {#agents---specialized-reviewers} @@ -2189,6 +2189,17 @@ An autonomous research agent that runs continuous experiments --- modifying code RMSE of ATT estimate. Lower is better. Report coverage rate alongside. ``` +## stata-mcp: MCP server for Stata execution + +**Repository:** [SepineTam/stata-mcp](https://github.com/SepineTam/stata-mcp) +**Author:** SepineTam (171+ stars, 91 releases, v1.17.3 as of May 2026) + +A mature MCP server that lets Claude Code execute Stata `.do` files via a command-guarded interface — refuses destructive shell ops (`!/shell/erase` etc.), monitors RAM, and pairs with the Stata Language Server. **Install once per user:** `claude mcp add stata-mcp --scope user -- uvx stata-mcp` (requires `uv` and a local Stata install). + +**Why it matters for this template:** v1.9.0 added [`/stata-replication`](#sec-appendix) for Stata-first projects, which depends on this MCP server. R-first projects (the original template focus) continue to use [`/data-analysis`](#sec-appendix); the two skills are parallel — same pipeline shape, different source language. AEA submissions where the original replication package is in Stata are the canonical use case. + +For end-to-end Stata workflows, see [`.claude/rules/stata-code-conventions.md`](.claude/rules/stata-code-conventions.md) (header scaffold, numbered pipeline, esttab tables, clustering discipline, AEA Data Editor compliance). + ## ClaudeCodeTools: The Editor Persona **Repository:** [aspi6246/ClaudeCodeTools](https://github.com/aspi6246/ClaudeCodeTools) @@ -2590,6 +2601,7 @@ Claude Code supports **plugins** --- bundled collections of skills, agents, hook | `/prompt-only` | `.claude/skills/prompt-only/` | Same formatting as `/prompt` but emits the prompt as a reusable artifact (no execution) (v1.9.0) | | `/compress-session` | `.claude/skills/compress-session/` | Distil the current session into a structured note (decisions, files, open questions, next actions, discarded-as-noise) before auto-compaction (v1.9.0) | | `/promote-memory` | `.claude/skills/promote-memory/` | Five-critic council that votes on whether candidate `[LEARN]` entries should be promoted from personal-memory.md to MEMORY.md (v1.9.0) | +| `/stata-replication` | `.claude/skills/stata-replication/` | End-to-end Stata pipeline scaffold + execution via the `stata-mcp` MCP server (mirrors `/data-analysis` for R-first projects; v1.9.0) | ## All Rules @@ -2627,6 +2639,7 @@ Claude Code supports **plugins** --- bundled collections of skills, agents, hook | Summary–Body Parity | `summary-parity.md` | `CHANGELOG.md`, `README.md`, `.qmd`, skill/rule/agent `.md` | | Post-Flight Verification | `post-flight-verification.md` | skills that generate factual claims (`/lit-review`, `/research-ideation`, `/respond-to-referees`, `/review-paper`, `/interview-me`) | | Model Routing | `model-routing.md` | `.claude/agents/**/*.md`, `.claude/skills/**/SKILL.md` — 70/20/10 architect/editor split, per-agent `model:` field guidance (v1.9.0) | +| Stata Code Conventions | `stata-code-conventions.md` | `**/*.do`, `scripts/stata/**` — header scaffold, numbered pipeline, esttab tables, clustering discipline, AEA compliance (v1.9.0) | ## Hooks diff --git a/templates/skill-template.md b/templates/skill-template.md index 7b295b47d..82909b184 100644 --- a/templates/skill-template.md +++ b/templates/skill-template.md @@ -437,4 +437,4 @@ When adapting this template to your domain: - **Purpose:** Starter for domain-specific skills - **Usage:** Copy to `.claude/skills/[name]/SKILL.md`, customize for your field -For existing skills examples, see `.claude/skills/` directory (35 skills for LaTeX, R, Quarto, and research workflows). +For existing skills examples, see `.claude/skills/` directory (36 skills for LaTeX, R, Quarto, and research workflows).