Econ Paper Studio

Econ Paper Studio

End-to-end empirical economics workflow. Stages: skills → question → design → data contract → execute → evidence ledger → claim audit → reviewer gauntlet → write. Chinese-friendly. Stata-first.

> WORKFLOW.md is the single source of truth for the five-stage pipeline. This file is the Cursor/Claude Code skill entry that describes activation conditions and routing rules.

Required Companion Skills

When the platform has these skills available, load them before doing substantive work:

1. superpowers:using-superpowers
2. superpowers:executing-plans
3. superpowers:systematic-debugging
4. superpowers:verification-before-completion
5. data:statistical-analysis
6. data:validate-data
7. data:create-viz
8. content-research-writer
9. documents:documents

Detailed purpose, fallback behavior, and upstream installation guidance are documented in docs/SKILL_LOADOUT.md and docs/UPSTREAM_SKILLS.md. The same loadout is also available as machine-readable metadata in skill_loadout.yaml.

Do not treat missing companion skills as a reason to stop. Fall back to the local CLI gates: doctor, skills plan, identify, design-memo, data-audit, scaffold, ledger, verify, claim-audit, reviewer-gauntlet, paper audit, and session.

When to Use This Skill

Yes:

• Causal inference: DiD, RDD, IV, SCM, PSM, DML, Causal Forest
• Empirical paper writing: from data to draft to R&R response
• Identification strategy selection given research question + data structure
• Robustness checks automation (parallel trends, placebo, multiple testing correction, heterogeneity)
• Chinese journal submission (CSSCI, CSI Tier 1)
• Stata-heavy workflows where most upstream tools are Python/R
• Referee response drafting (point-by-point)

No:

• Pure ML / non-causal prediction (use scikit-learn directly)
• Theory-only papers without empirics
• Bibliometric reviews (use OpenAlex MCP directly)
• One-off regression in Jupyter (overkill)

Default Mode: Quick or Full?

Quick mode — User has a clear brief and wants to skip to one specific stage:

• "I have data and want to know if DiD is appropriate" → jump to stage 2 (design)
• "I have a draft, run robustness checks" → jump to stage 4 (verify)

Full mode — User has fuzzy intent or high-stakes deliverable:

• "I want to write a paper about X" → start at stage 1 (question)
• Mentions "submit to" / "客户" / "投稿" / "blind review"

Default is quick mode. Switch to full when the brief has fewer than 3 of {research question, identification strategy, data, target journal, expected contribution}.

The Core Stages

Stage 0: skills (upstream routing and safety)

Tool: scripts/skills.py

python scripts/skills.py plan --task full-paper
python scripts/skills.py audit --dir _references/upstream-skills/some-skill

Use plan before substantial work so the agent knows which upstream skills to load for literature, design, execution, writing, claim audit, review, and submission. Use audit before loading a third-party skill directory; it checks for missing SKILL.md, network calls, environment/secret access, SSH key patterns, and browser-data access.

Stage 1: question (research question clarification)

Tool: RESEARCH_QUESTION.md template (5 core questions + 5 advanced)

Skip if: User already has a clear "X has a causal effect on Y in context Z" brief plus identification strategy and target journal.

Use if: User says "I want to study minimum wage effects" with no further detail.

Read [RESEARCH_QUESTION.md](./RESEARCH_QUESTION.md). Ask the 5 core questions: research question, contribution, journal, data, identification strategy seed. Stop generating until the brief is structured.

Stage 2: design (identification strategy selection)

Tool: scripts/identify_strategy.py decision tree

Skip if: Strategy locked + literature benchmark known.

Use if: User asks "what method?" or has data but no method yet.

Run:

python scripts/identify_strategy.py --brief research_brief.yaml

Outputs strategy_recommendation.md with primary method, alternatives, ≥3 literature benchmarks, robustness checklist, and StatsPAI function call preview.

Then render the identification contract:

python scripts/evidence_pipeline.py design-memo --brief research_brief.yaml --output design_memo.md

Stage 3: data-audit + execute

Tool: scripts/data_audit.py first, then scripts/scaffold.py.

python scripts/data_audit.py --csv data/analysis_panel.csv \
  --key unit_id --key year \
  --outcome outcome \
  --treatment treatment \
  --cluster unit_id \
  --fail-on-critical

python scripts/scaffold.py --strategy DiD --session my-paper --lang stata

data_audit.py checks duplicate keys, missingness, treatment variation, numeric outcome, and cluster count before estimation. scaffold.py outputs outputs// with standard subdirectories and Stata/R analysis files:

• do/00_master.do or R/00_main.R — ordered execution entry
• 01_clean / 02_descriptive / 03_main — core empirical workflow
• 04_robustness / 05_heterogeneity / 99_export — checks and paper outputs
• data/, tables/, figures/, robustness/ — replication package structure

The data-audit report now includes a data contract: analysis grain, join explosion risk, denominator boundary, missingness boundary, cluster level, and claim boundary.

Stage 3.5: evidence ledger

Tool: scripts/evidence_pipeline.py ledger

python scripts/evidence_pipeline.py ledger init --ledger evidence_ledger.json
python scripts/evidence_pipeline.py ledger add --ledger evidence_ledger.json \
  --artifact-id table1 \
  --title "Baseline DiD estimates" \
  --artifact-path tables/table1.tex \
  --code-path do/03_main.do \
  --data-source data/analysis_panel.csv \
  --sample "city-year panel" \
  --model "two-way fixed effects DiD" \
  --estimand ATT \
  --cluster city_id \
  --claim "Minimum wage changes affect youth employment"
python scripts/evidence_pipeline.py ledger audit --ledger evidence_ledger.json

Every table and figure that supports a paper claim should have a ledger row.

Stage 4: verify (robustness + audit)

Tool: scripts/robustness_checks.py

python scripts/robustness_checks.py --strategy DiD --analysis outputs/my-paper --output verify_report.md

Checks:

• Critical: parallel trends (DiD), McCrary density (RDD), weak IV F-stat (IV), cluster SE used, multiple testing correction
• High: placebo, heterogeneity, alternative bandwidth/cluster levels, HonestDiD sensitivity, selection (Heckman/Lee bounds)
• Audit: AI-style filler phrases, obvious citation placeholders, missing references section risk

This verifier is a static gate. It does not prove numerical correctness or source support; use it before live Stata/R/Python runs and external citation verification so the agent does not skip required evidence.

Stage 5: paper/write (outline, audit, session)

Tool: scripts/paper_pipeline.py for outline/audit and scripts/session.py for version history.

python scripts/paper_pipeline.py outline --brief research_brief.yaml --output paper_outline.md
python scripts/paper_pipeline.py audit --paper draft.md --output paper_audit.md --fail-under 8
python scripts/session.py init my-paper --rq "X causes Y" --strategy DiD --target-journal CSSCI
python scripts/session.py add my-paper --version v1 --paper draft_v1.docx --note "first draft"
python scripts/session.py add-review my-paper --version r1 --letter comments.docx --decision major
python scripts/session.py promote my-paper --version v2

paper_pipeline.py checks core sections, explicit contribution, obvious citation placeholders, causal overclaim risk, filler phrases, and figure/table caption quality. It does not verify that a citation exists or supports a claim. session.py maintains manifest.json + CHANGELOG.md per session.

Before treating a draft as ready, run:

python scripts/evidence_pipeline.py claim-audit --paper draft.md --ledger evidence_ledger.json
python scripts/evidence_pipeline.py reviewer-gauntlet --paper draft.md --ledger evidence_ledger.json

claim-audit maps explicit Claim: statements back to evidence-ledger entries. reviewer-gauntlet applies five views: Method Reviewer, Data Auditor, Citation Auditor, Writing/Humanizer, and Replication Editor.

Things That Must Survive Compilation

When advising on the workflow, never lose:

• Identification strategy first, then data. A clever method on bad data ≥ a bad method on good data ≥ no method.
• Cluster SE always. Default cluster level: panel ID for individuals, treatment unit for staggered policies, region for shocks.
• Multiple testing correction when running >1 hypothesis. Bonferroni or Holm-Šídák, not just `p 3.10** required (StatsPAI dependency)
• Optional: Stata installation (for stata-mcp) — most scripts work without it via fallback
• Optional: Volcengine ARKAPIKEY for vision-based table verification
• Optional: Semantic Scholar API key for citation validation (free tier OK)

This skill is at version 0.3.1. The CLI gates are runnable; external citation verification and real Stata/R/Python execution remain explicit live-tool steps.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gaaiyun
• Source: gaaiyun/econ-paper-studio
• License: MIT

Install and usage instructions live in the source repository linked above.