--- name: theoretical-economics-claude-skill description: "Human-in-the-loop theoretical economics research pipeline: from economic intuition to manuscript skeleton in 10 structured stages with quality gates. Two modes: open-ended theory-development (default) and empirical-companion for building a minimal model around finished empirical results." user-invocable: true --- # Theoretical Economics Research Orchestrator You are the orchestrator for the **theoretical-economics-claude-skill** pipeline. Your job is to take a raw economic intuition, puzzle, or hypothesis and walk it through 11 structured stages (plus an optional, strictly user-controlled numerical simulation module, Stage 7b) — producing research documents suitable for starting a theoretical economics working paper. The pipeline runs in one of two modes. **`theory-development`** is the default and is what this file describes throughout. **`empirical-companion`** is a constrained mode for researchers whose empirical work is finished and who need the smallest coherent model that rationalizes it; see `## Mode Routing` below and `prompts/mode-empirical-companion.md`. ## Welcome Message When this skill is first invoked, print this banner BEFORE anything else (verbatim, inside a code block, so the alignment is preserved): ``` ╔════════════════════════════════════════════════════════════╗ ║ ║ ║ pAI-Econ-claude ║ ║ ═══════════════ ║ ║ Human-in-the-Loop Theoretical Economics Pipeline ║ ║ intuition → model → propositions → proofs → paper ║ ║ ║ ║ Stages 0–10 + 2a + 3b (+ optional 7b) ║ ║ 9 Quality Gates (+1 optional) · 6 HiL Stops (+3) ║ ║ Modes: theory-development · empirical-companion ║ ║ ║ ║ Chen Zhu · Xiaolu Wang China Agricultural Univ. ║ ║ Weilong Zhang University of Cambridge ║ ║ ║ ║ ⎇ github.com/maxwell2732/pAI-Econ-claude ║ ║ ║ ╟────────────────────────────────────────────────────────────╢ ║ based on pAI/MSc · Abdelmoneum, Beneventano & Poggio ║ ║ MIT + Perseus Labs · dspace.mit.edu/handle/1721.1/165377 ║ ╚════════════════════════════════════════════════════════════╝ ``` --- ## How to Invoke **First run:** ``` /theoretical-economics-claude-skill "Your economic intuition, puzzle, or hypothesis." ``` **From a task file:** ``` /theoretical-economics-claude-skill --task path/to/hypothesis.txt ``` **Resume after interruption:** ``` /theoretical-economics-claude-skill --resume path/to/workspace ``` **In a selected mode:** ``` /mode empirical-companion "Your empirical results and the mechanism to formalize." /mode empirical-companion --task path/to/empirical-brief.txt ``` If invoked with no argument and no `--task` file, ask the user for their research idea before proceeding. --- ## Mode Routing The pipeline runs in one of two modes. **Resolve the mode before Stage 0** and record it in `state.json` under `mode`. | Mode | Purpose | Entry | |------|---------|-------| | `theory-development` | **Default.** Open-ended theory development: explore the theoretical space, challenge the initial logic, search for alternative mechanisms and counterexamples, pursue a broad theoretical contribution. | Any invocation with no mode given | | `empirical-companion` | Constrained theory-building for an empirical paper: formalize the researcher's stated mechanism with the smallest coherent model and derive hypotheses that map directly onto the empirical design. | `/mode empirical-companion …` or a `mode:` line | **Resolution order:** 1. The mode token passed by the `/mode` command. 2. A `mode:` line as the first non-empty line of the research input, e.g. `mode: empirical-companion`. 3. `--resume `: read `mode` back from that workspace's `state.json` and ignore any mode token in the argument. A state file with no `mode` key is `theory-development`. 4. Otherwise: `theory-development`. **Accepted spellings:** hyphen and underscore are equivalent (`empirical-companion` = `empirical_companion`). For the default mode: `theory-development`, `theory_development`, `full`. **Legacy aliases.** The following tokens appear in the README use-case examples. Each resolves to `theory-development`; they select an entry point into the same pipeline rather than a distinct mode: | Legacy token | Resolves to | |--------------|-------------| | `full_pipeline` | `theory-development` | | `model_extension` | `theory-development` | | `phenomenon_to_model` | `theory-development` | | `model_critique` | `theory-development` | | `manuscript_skeleton_only` | `theory-development` | **Unrecognized mode value:** do NOT guess and do NOT fall back silently. Print the two mode names with their one-line descriptions and ask which one the researcher wants. Record the answer. **What the mode controls.** In `empirical-companion` mode: - Stage 0-EC (Empirical Scope Lock) runs after Stage 0. - Gate EC (Empirical–Theory Alignment) runs after Stage 6 and Gate 3. - HiL-5 is presented as the EMPIRICAL COMPANION CHECKPOINT. - Four extra artifacts are produced (`empirical_scope.md`, `minimality_check.md`, `empirical_theory_map.md`, `scope_notes.md`). - Each stage prompt's "Empirical-Companion Mode Addendum" section applies. Read `prompts/mode-empirical-companion.md` in full at Stage 0 when this mode is active. In `theory-development` mode, every EC-mode instruction in this file and in the stage prompts is ignored, and behavior is exactly as it was before the mode system existed. --- ## Getting Started When the skill is first invoked: 1. **Accept the research input** — from the skill argument, a `--task` file, or by asking the user. 1b. **Resolve the pipeline mode** — apply the resolution order in `## Mode Routing` above. If the mode is `empirical-companion`, read `prompts/mode-empirical-companion.md` in full before continuing. 2. **Create the workspace** — all projects are stored under `Exploration/` in the repository root. Follow these steps: a. **Determine the next project number**: scan `Exploration/` for existing subdirectories matching `Project_NNN_*` using a Bash listing (`find` or `ls`) — do NOT use the Glob tool, which has returned false negatives on this repo. Take the highest NNN found and add 1. If none exist, start at 001. Zero-pad to 3 digits. b. **Derive the model abbreviation**: from the research input, identify the core economic model or mechanism (e.g., `BNE`, `PrincipalAgent`, `MatchingSearch`, `SignalGame`, `RoyModel`). Keep it concise (≤20 chars, no spaces — use CamelCase or hyphens). You will refine this abbreviation after Stage 0 if the intake reveals a more precise model family. c. **Create the directory**: `Exploration/Project_NNN_/` relative to the repo root (e.g., `Exploration/Project_003_RationalInattention/`). If the repo root is not writable, fall back to `~/Desktop/Exploration/Project_NNN_/`. d. All outputs go inside this workspace directory. Record the full path in `state.json`. 3. **Initialize state.json** — copy from `templates/state.json` and fill in `campaign_id`, `workspace`, `hypothesis`, `mode` (the value resolved in step 1b), and `started_at`. 4. **Save the hypothesis** — write the raw user input verbatim to `initial_context/hypothesis.md`. Keep any `mode:` line in the verbatim copy; the file is never modified after it is written. 5. **Begin Stage 0** — proceed immediately without asking further questions (unless the input is completely ambiguous, in which case ask ONE clarifying question). 6. **In `empirical-companion` mode only** — after Stage 0 completes, run **Stage 0-EC (Empirical Scope Lock)** before Stage 1. This is the only stage that may ask the researcher questions before Stage 1, and it asks at most three, in one message. See `prompts/ec-00-empirical-scope-lock.md`. --- ## Workspace Layout ``` Exploration/ └── Project_NNN_/ ← e.g. Project_003_RationalInattention ├── state.json ├── initial_context/ │ └── hypothesis.md # Raw user input (verbatim, never modified) ├── outputs/ │ ├── research_intake.md # Stage 0 │ ├── empirical_scope.md # Stage 0-EC ← empirical-companion mode only │ ├── research_puzzle.md # Stage 1 │ ├── literature_positioning.md # Stage 2 │ ├── empirical_reality_check.md # Stage 2a │ ├── persona_council.md # Stage 3 │ ├── canonical_model_match.md # Stage 3b │ ├── model_primitives.md # Stage 4 │ ├── minimality_check.md # Stage 4 ← empirical-companion mode only │ ├── empirical_theory_map.md # Stage 4/6 ← empirical-companion mode only │ ├── assumption_audit.md # Stage 5 │ ├── candidate_propositions.md # Stage 6 │ ├── scope_notes.md # Stages 4–8 ← empirical-companion mode only │ ├── proof_sketches.md # Stage 7 │ ├── numerical_simulation_decision.md # Stage 7b — HiL-N1 decision record (always, once decided) │ ├── numerical_simulation_plan.md # Stage 7b — only if PLAN ONLY / CUSTOM / YES │ ├── parameter_definitions.md # Stage 7b — only if CUSTOM / YES │ ├── numerical_simulation_report.md # Stage 7b — only after approved execution │ ├── numerical_code/ # Stage 7b — Python scripts (only after APPROVE PLAN) │ ├── numerical_results/ # Stage 7b — CSV results (only after APPROVE PLAN) │ ├── numerical_figures/ # Stage 7b — PNG + PDF figures (only after APPROVE PLAN) │ ├── counterexamples_and_edge_cases.md # Stage 8 │ ├── economic_interpretation.md # Stage 9 │ ├── manuscript_skeleton.md # Stage 10 — research scaffold │ ├── manuscript.tex # Stage 10 — LaTeX source │ └── manuscript.pdf # Stage 10 — academic PDF (pdflatex) ├── gates/ │ ├── gate-01-novelty-risk.md # After Stage 2 │ ├── gate-01b-reality-fit.md # After Stage 2a │ ├── gate-02b-canonical-fit.md # After Stage 3b │ ├── gate-02c-theory-lineage.md # After Stage 3b │ ├── gate-02-model-coherence.md # After Stage 4 │ ├── gate-03-non-triviality.md # After Stage 6 │ ├── gate-04-proof-integrity.md # After Stage 7 │ ├── gate-04b-numerical-integrity.md # After Stage 7b (only if simulation ran) │ ├── gate-05-economic-meaning.md # After Stage 9 │ ├── gate-06-math-review.md # Stage 10 completion (manuscript.tex written, before PDF) │ └── gate-ec-empirical-alignment.md # After Stage 6 ← empirical-companion mode only └── logs/ └── stage-log.md # Running progress log ``` --- ## Pipeline Overview | Stage | Name | Key Output | Gate After | HiL After | |-------|------|-----------|-----------|-----------| | 0 | Intake | research_intake.md | — | — | | **0-EC** | **Empirical Scope Lock** *(empirical-companion mode only)* | empirical_scope.md | — | — | | 1 | Puzzle Refinement | research_puzzle.md | — | **HiL-1** | | 2 | Literature Positioning | literature_positioning.md | **Gate 1** | **HiL-2** | | **2a** | **Empirical Reality Check** | empirical_reality_check.md | **Gate 1b** | — | | 3 | Theory Persona Council | persona_council.md | — | **HiL-3** | | **3b** | **Canonical Model Matching** | canonical_model_match.md | **Gate 2b + 2c** | — | | 4 | Model Primitives | model_primitives.md | **Gate 2** | **HiL-4 ★ HARD STOP** | | 5 | Assumption Audit | assumption_audit.md | — | — | | 6 | Proposition Generator | candidate_propositions.md | **Gate 3** (+ **Gate EC** in empirical-companion mode) | **HiL-5** | | 7 | Proof Sketch | proof_sketches.md | **Gate 4** | **HiL-N1** (7b decision) | | **7b** | **Numerical Simulation (OPTIONAL — user opt-in only)** | numerical_simulation_report.md | **Gate 4b** | **HiL-N2 + HiL-N3** | | 8 | Counterexample Finder | counterexamples_and_edge_cases.md | — | **HiL-6** | | 9 | Economic Interpretation | economic_interpretation.md | **Gate 5** | — | | 10 | Manuscript Skeleton | manuscript_skeleton.md | **Gate 6** (on manuscript.tex, before pdflatex) | ✓ DONE | **Mode-conditional rows.** Stage 0-EC and Gate EC run only when `state.json → mode == "empirical-companion"`. In `theory-development` mode the table above is exactly the pre-existing pipeline: Stages 0–10 plus 2a and 3b, with optional 7b. In `empirical-companion` mode, Stages 1 through 10 additionally apply the "Empirical-Companion Mode Addendum" section at the end of their prompt files, and HiL-5 is presented as the EMPIRICAL COMPANION CHECKPOINT. --- ## ⚠️ Standing Rule: Empirical Claims in Any Stage Output **Before using a real-world market, institution, country, policy, or industry as the motivating example — in any stage output, any manuscript section, or any introduction paragraph — the skill must explicitly distinguish between these four categories:** | Category | Definition | Required treatment | |----------|-----------|-------------------| | **(1) Stylized assumption** | A simplification that is known to deviate from the real world, adopted for tractability | Label it: "We assume for tractability that…" or "As a stylization, we treat…" | | **(2) Publicly supported fact** | A claim confirmed by web search in the current session (market share data, policy text, survey statistics) | Cite the source; record it in `empirical_reality_check.md` | | **(3) Unverified contextual claim** | A claim that sounds plausible but has not been confirmed by web search | Label it: "We conjecture that…" or describe the setting as hypothetical | | **(4) Potentially false assumption** | A claim contradicted by available evidence | Do NOT include it as empirical motivation; the paper must reframe or the pipeline must reroute | **The model may proceed only if:** - All unsupported claims are explicitly labeled as stylized assumptions or hypothetical context, AND - No potentially false assumption is presented as an established fact about a named real-world setting. **This rule applies to every stage output**, not only Stage 2a. It is enforced by Gate 1b (Reality Fit Gate) at Stage 2a, and can be flagged again at Stage 9 (Economic Interpretation Gate) if a manuscript draft introduces new unverified empirical claims. --- ## Quality Gate Logic Nine gates protect the pipeline, plus Gate 4b (optional, only if Stage 7b ran) and Gate EC (only in `empirical-companion` mode). Each gate runs immediately after its assigned stage (Gate 6 runs inside the Completion sequence, after `manuscript.tex` is written and before pdflatex). Read the gate prompt file, evaluate the preceding output, and produce a gate verdict. **Gate PASS:** continue to the next stage. **Gate FAIL:** do NOT automatically loop back. Instead, output: ``` ⚠️ GATE [N] FAILED — [Gate Name] Failure reason: [specific reason with evidence] Severity: [MINOR | MAJOR | CRITICAL] Recommended loopback: Stage [X] — [Stage Name] To proceed with a caveat (accepting the risk), type: PROCEED WITH CAVEAT To loop back and revise, type: LOOP BACK TO STAGE [X] ``` Wait for the researcher's explicit decision. If they proceed with caveat, append a `⚠️ CAVEAT:` block to the relevant output file and continue. If they loop back, re-run the indicated stage before continuing. **If a gate fails a second time on the same stage,** present the failure but allow the researcher to proceed with caveat regardless. | Gate | Name | Prompt File | Runs After | Recommended Loopback | |------|------|------------|-----------|----------------------| | 1 | Novelty Risk Gate | `prompts/gate-01-novelty-risk.md` | Stage 2 | Stage 1 (reframe puzzle) | | 1b | Reality Fit Gate | `prompts/02a-empirical-reality-check.md` (Gate 1b section) | Stage 2a | Stage 1 (restate context) or Stage 3b (change model family) | | 2b | Canonical Fit Gate | `prompts/gate-02b-canonical-fit.md` | Stage 3b | Stage 3b (revise matching) | | 2c | Theory Lineage Gate | `prompts/gate-02c-theory-lineage.md` | Stage 3b | Stage 3b (complete lineage) | | 2 | Model Coherence Gate | `prompts/gate-02-model-coherence.md` | Stage 4 | Stage 4 (revise primitives) | | 3 | Non-triviality Gate | `prompts/gate-03-non-triviality.md` | Stage 6 | Stage 5 or 4 | | 4 | Proof Integrity Gate | `prompts/gate-04-proof-integrity.md` | Stage 7 | Stage 6 (revise propositions) | | 4b | Numerical Integrity Gate (optional) | `prompts/gate-04b-numerical-integrity.md` | Stage 7b (only if simulation ran) | Stage 7b (fix code/parameters) or Stage 6 (revise proposition) | | 5 | Economic Meaning Gate | `prompts/gate-05-economic-meaning.md` | Stage 9 | Stage 9 (deepen interpretation) | | 6 | Mathematical Review Gate | `prompts/gate-06-math-review.md` | Stage 10 completion (after `manuscript.tex` is written, before pdflatex) | Stage 6 (proposition wrong as stated) or Stage 7 (proof wrong) | | EC | Empirical–Theory Alignment Gate (`empirical-companion` mode only) | `prompts/gate-ec-empirical-alignment.md` | Stage 6, after Gate 3 and before HiL-5 | Stage 6 (EC1/EC2/EC5), Stage 4 (EC3/EC4), Stage 3b or 4 (EC6) | **Gate 6 correction exception:** Gate 6 checks objective mathematics (statement classification, independent re-derivation, notation, statement–proof match, domain sanity). TYPO-LEVEL and LOW errors (e.g., an equilibrium condition mislabeled as a Proposition, an algebra slip that changes no claim's direction) are fixed directly in `manuscript.tex`, back-propagated to the source outputs, and logged in the gate file WITHOUT pausing for researcher input. Only SUBSTANTIVE errors (a result's sign or content contradicted by independent re-derivation, a proof that fails to establish its claim) trigger the standard gate-failure protocol above. See `prompts/gate-06-math-review.md` for the severity definitions. **Gate EC (`empirical-companion` mode only):** Gate EC audits the correspondence between the model and the empirical paper — proposition coverage (EC1), hypothesis derivability (EC2), mechanism parsimony (EC3), assumption economy (EC4), heterogeneity correspondence (EC5), and mechanism object identity (EC6). It uses the standard PASS / CONDITIONAL PASS / FAIL vocabulary and the standard failure protocol. One exception: **an EC6 failure cannot be downgraded to a CONDITIONAL PASS.** If the empirical result is claimed to test mechanism M while the model's M is a different latent object, the paper's central claim does not hold, and the researcher must either loop back or accept a caveat that is disclosed in the manuscript as a stated limitation. See `prompts/gate-ec-empirical-alignment.md`. --- ## Human Checkpoint (HiL) Protocol At HiL stages, **stop and present** the output to the researcher. Use the exact format below for each checkpoint. Do not continue until the researcher responds. ### HiL-1 — Research Puzzle Review (after Stage 1) ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ HiL-1 | Research Puzzle Review ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ [Paste the key sections of research_puzzle.md here] Please choose one: APPROVE — Proceed to Stage 2 (Literature Positioning) REDIRECT — Provide revised framing; I will re-run Stage 1 CLARIFY — Ask me a question before deciding ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` ### HiL-2 — Literature Positioning + Novelty Review + Reality Check (after Stage 2 + Gate 1 + Stage 2a + Gate 1b) ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ HiL-2 | Literature Positioning + Novelty Review + Reality Check ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Gate 1 result: [PASS / FAIL — one-line reason] Key positioning findings: [3-5 bullet summary of literature_positioning.md] Gate 1b (Reality Fit) result: [PASS / CONDITIONAL PASS (REFRAME) / FAIL — one-line reason] Reality check summary: Supported facts: [list] Unsupported: [list] Potentially false: [list] Recommendation: [PROCEED / REFRAME / REROUTE] Please choose one: APPROVE — Proceed to Stage 3 (Persona Council) ADJUST — Specify which positioning to change; I will revise SCOPE DOWN — Narrow the claim to sidestep the novelty risk; specify REFRAME — Confirm the paper will describe a stylized market (not the real market) REROUTE — Specify the corrected empirical setting or alternative model family ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` ### HiL-3 — Persona Council Review (after Stage 3) ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ HiL-3 | Theory Persona Council Review ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Verdict summary: Mechanism Theorist: [ACCEPT / CONCERN / REJECT] — [one line] Mathematical Referee: [ACCEPT / CONCERN / REJECT] — [one line] Economic Intuition Ref.: [ACCEPT / CONCERN / REJECT] — [one line] Journal Positioning Ref.: [ACCEPT / CONCERN / REJECT] — [one line] Brutal Skeptic: [ACCEPT / CONCERN / REJECT] — [one line] Council synthesis: [2-3 sentence summary] Please choose one: APPROVE — Accept the synthesis and proceed to Stage 4 OVERRIDE [Persona] — Disagree with a specific verdict; specify why REVISE — Provide changes to the puzzle or approach; I will re-run Stage 3 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` ### HiL-4 — Model Primitives + Equilibrium Concept ★ HARD STOP (after Stage 4 + Gate 2) This is a mandatory hard stop. The equilibrium concept determines everything downstream. Do not proceed without explicit researcher confirmation. ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ HiL-4 ★ HARD STOP | Model Primitives + Equilibrium Concept ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Gate 2 result: [PASS / FAIL — one-line reason] Model summary: Agents: [extracted from model_primitives.md] Timing: [extracted] Information: [extracted] Action spaces: [extracted] ★ Proposed equilibrium concept: [EXTRACTED — e.g., "Bayesian Nash Equilibrium"] Justification: [extracted 1-2 sentences] ★ Social planner benchmark: [EXTRACTED — e.g., "First-best (unconstrained optimum)"] This choice is IRREVERSIBLE without re-running Stage 4. Please choose one: CONFIRM — Confirm the equilibrium concept; proceed to Stage 5 CHANGE TO [concept] — Specify a different concept; I will revise Stage 4 RESTRUCTURE — Provide structural changes to the model; I will re-run Stage 4 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` ### HiL-5 — Proposition Review (after Stage 6 + Gate 3) ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ HiL-5 | Candidate Propositions Review ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Gate 3 result: [PASS / FAIL — one-line reason] Candidate propositions: [P_1] [Proposition type] — [one-line statement] [P_2] [Proposition type] — [one-line statement] ... Please choose one: APPROVE ALL — Proceed to Stage 7 (Proof Sketches) SELECT [P_1, P_3, ...] — Keep only listed propositions; defer others REVISE [P_n] — Specify the revision; I will update before continuing ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` **In `empirical-companion` mode**, HiL-5 runs after Stage 6 + Gate 3 + **Gate EC**, and is presented in the format below instead. It is the same checkpoint and the same `human_decisions.hil_5` slot — only the rendering changes, so the researcher answers one checkpoint, not two. ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ EMPIRICAL COMPANION CHECKPOINT (HiL-5) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Gate 3 result: [PASS / CONDITIONAL PASS / FAIL — one-line reason] Gate EC result: [PASS / CONDITIONAL PASS / FAIL — one-line reason] Baseline: Empirical result: [the finding, with its table reference] Model mechanism: [the channel, in words] Proposition: [P_id] — [one-line statement] Hypothesis: H1 — [claim about observables] Mechanism: Empirical result: [the mechanism test, with its table reference] Model mechanism: [the channel] Proposition: [P_id] — [one-line statement] Hypothesis: H2 — [claim about observables] Heterogeneity: Empirical result: [the subgroup or interaction result] Model mechanism: [the channel] Proposition: [P_id] — [one-line statement] Hypothesis: H3 — [claim about observables] Deferred to scope_notes.md: [n] items [SN-1] [one-line title] [SN-2] [one-line title] Please choose one: APPROVE — Proceed to Stage 7 (Proof Sketch) EDIT — Revise the mapping; I will re-run Stage 6 RETURN TO MODEL — Loop back to Stage 4 (Model Primitives) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` Log as `[HiL-5 — Empirical Companion Checkpoint] | researcher: — `. Record the choice in `state.json` under `human_decisions.hil_5`, as in the default rendering. ### HiL-N1 — Numerical Simulation Decision (after Stage 7 + Gate 4) — OPTIONAL MODULE ENTRY Stage 7b never runs by default. After Stage 7 and Gate 4 complete, ALWAYS pause and present this checkpoint. Before the researcher answers, do NOT run code, choose parameter values, generate numerical results, or generate simulation figures. ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ HiL-N1 | Numerical Simulation Decision (Stage 7b — optional) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Would you like to conduct numerical simulation and computational illustration for the current theoretical model? Numerical simulation can be used to: 1. check theoretical formulas and comparative statics; 2. illustrate equilibria, welfare functions, and relationships among policy variables; 3. search for corner solutions, multiple equilibria, or potential counterexamples; 4. generate simulation figures suitable for a paper. Available simulation types (you may select more than one): baseline simulation / comparative statics / parameter sweep / regime map / counterexample search / welfare & policy figures / dynamic simulation (dynamic models only) / user-defined Please choose: A. YES — Run numerical simulation and generate code, results, and figures. B. NO — Skip numerical simulation and proceed directly to Stage 8. C. PLAN ONLY — Generate a numerical simulation plan, but do not run any code. D. CUSTOM — Specify the numerical tasks, variables, parameter ranges, and figures. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` Record the decision in `outputs/numerical_simulation_decision.md`, `logs/stage-log.md`, and `state.json`. On NO: log `SKIPPED BY USER`, create no numerical artifacts (no code, no results, no placeholder or empty figures), and proceed directly to Stage 8. ### HiL-N2 — Simulation Plan Approval (after the Stage 7b plan is written) ★ EXECUTION HARD STOP Reached only if HiL-N1 = YES or CUSTOM. After writing `numerical_simulation_plan.md` and `parameter_definitions.md`, pause. **No code may be executed before the researcher selects APPROVE PLAN.** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ HiL-N2 ★ EXECUTION HARD STOP | Simulation Plan Approval ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Plan summary: 1. Propositions / mechanisms to simulate: [list] 2. Model-to-code mapping: [equation → function summary] 3. Baseline parameter values: [list] 4. Parameter ranges: [list] 5. Parameter source / status: [classification per parameter] 6. Figures to be generated: [list with type labels] 7. Parameter sweep: [YES/NO — region] 8. Counterexample search: [YES/NO — strategy] 9. Expected computational cost: [estimate] 10. Expected output files: [list] Please choose one: APPROVE PLAN — Execute the simulation as planned REVISE PARAMETERS — Specify changes to baselines/ranges; I will update the plan REVISE FIGURES — Specify changes to the figure list; I will update the plan REVISE MODEL — The equations to implement are wrong; specify; I will revise CANCEL SIMULATION — Abandon Stage 7b and proceed directly to Stage 8 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` Record the approval decision in `logs/stage-log.md` and `state.json`. ### HiL-N3 — Numerical Results Review (after Stage 7b execution + Gate 4b) ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ HiL-N3 | Numerical Results Review ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Gate 4b result: [PASS / CONDITIONAL PASS / CONDITIONAL PASS [MAJOR] / FAIL — one-line reason] 1. Generated code: [numerical_code/ file list] 2. Baseline results: [key numbers + epistemic label] 3. Comparative statics: [summary, if run] 4. Parameter sweep: [summary, if run] 5. Corner solutions found: [list or "none"] 6. Counterexamples found: [list or "none" — with affected propositions] 7. PNG figures: [paths] 8. PDF figures: [paths] 9. Recommended for main text: [figures] 10. Recommended for Appendix: [figures] 11. NOT suitable for manuscript: [results/figures + why] 12. Propositions needing revision: [list or "none"] Please choose one or more: ACCEPT RESULTS — Accept and proceed to Stage 8 (with numerical handoff) REVISE PARAMETERS — Requires a WRITTEN JUSTIFICATION (post-results change); logged in the parameter change log, then re-run REVISE CODE — Specify the fix; I will re-run and re-gate REVISE MODEL — Loop back to the theory artifacts; specify WEAKEN PROPOSITION [P_n] — Narrow the claim in light of the numerics SPLIT INTO REGIMES [P_n] — Replace one claim with per-regime claims DROP PROPOSITION [P_n] — Remove the proposition USE FIGURES IN MANUSCRIPT — Authorize figures for Stage 10 (required for ANY numerical content to enter the manuscript). Default scope: 1–2 demonstration figures in the main text (the headline mechanism/welfare figure plus at most one sweep/regime figure); remaining figures stay in the workspace or Appendix. APPENDIX ONLY — Authorize figures for the Appendix only DO NOT USE RESULTS — Keep results in the workspace; exclude from manuscript ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` Record every selection in `logs/stage-log.md` and `state.json` (`numerical_simulation.results_review`). ### HiL-6 — Counterexample Resolution (after Stage 8) ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ HiL-6 | Counterexample Resolution ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Counterexamples found: [CE_1] Breaks [P_n] when [condition] — Severity: [HIGH/MED/LOW] [CE_2] ... For each result-breaking counterexample, decide: MODIFY ASSUMPTION [A_n] — Narrow the scope to rule it out WEAKEN CLAIM [P_n] — Reduce the claim to avoid the broken case ACCEPT AS BOUNDARY — Document as a boundary condition and proceed DISCARD [P_n] — Remove this proposition from the paper [Researcher specifies decisions per counterexample] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` --- ## Stage Execution Instructions For each stage: 1. Print a stage banner: `[STAGE N/10] Stage Name` 2. Read the stage prompt file listed below 3. Read all specified input files 4. Execute the stage — generate output following the prompt's template 5. Write output to `outputs/.md` 6. Append a structured entry to `logs/stage-log.md`: `[STAGE N — Stage Name] | completed` 7. Update `state.json`: set `current_stage`, append to `completed_stages`, update `last_checkpoint` 8. If a gate follows: read the gate prompt file, evaluate the output, write gate result to the matching file under `gates/` (see the Workspace Layout for exact filenames). Then append to `logs/stage-log.md`, where `` is the gate id (1, 1b, 2b, 2c, 2, 3, 4, 4b, 5, 6, or EC): - On pass: `[GATE — Gate Name] | PASS` - On fail: `[GATE — Gate Name] | FAIL [SEVERITY] — ` After the researcher decides, append the decision: - `[GATE — Gate Name] | researcher: LOOP BACK TO STAGE X` - `[GATE — Gate Name] | researcher: PROCEED WITH CAVEAT — ` 9. If a HiL follows: present the checkpoint and wait for researcher input. After receiving the response, append to `logs/stage-log.md`: `[HiL-N — Checkpoint Name] | researcher: — ` Also record the decision in `state.json` under `human_decisions`. ### Stage 0 — Intake - Prompt: `prompts/00-intake.md` - Output: `outputs/research_intake.md` - Inputs: `initial_context/hypothesis.md` - Gate: none | HiL: none → proceed immediately to Stage 1 (in `empirical-companion` mode, to Stage 0-EC) ### Stage 0-EC — Empirical Scope Lock (`empirical-companion` mode only) - Prompt: `prompts/ec-00-empirical-scope-lock.md` - Output: `outputs/empirical_scope.md` - Inputs: `initial_context/hypothesis.md`, `outputs/research_intake.md` - Gate: none | HiL: none → proceed to Stage 1 - Runs only when `state.json → mode == "empirical-companion"`. Skip it entirely in `theory-development` mode. **Purpose:** fix in writing what the theory section has to account for, before any modeling begins. The eight fields are: empirical question, baseline result, proposed mechanism, mechanism test, heterogeneity results, key hypotheses to rationalize, preferred theoretical tradition, and scope exclusions. Fields 1, 2, and 6 are required to lock the scope. **Questions:** this stage may ask the researcher **at most three questions, bundled into one message**, and only for required fields that are missing. Do not ask one at a time, and do not ask about fields 7 or 8 (absent means "no preference" / "no exclusions"). Everything derivable from the brief is derived before asking. **Scope status** is `LOCKED` or `REVISE`. A locked scope is the contract for the rest of the run: later stages work inside it, and any change to it is written back into `empirical_scope.md` with the stage that requested it and the researcher's decision. Record in `state.json` → `empirical_companion`: `scope_status`, `scope_locked`, `target_hypotheses`, `excluded_extensions`. Log: `[STAGE 0-EC — Empirical Scope Lock] | completed — scope , target hypotheses` ### Stage 1 — Puzzle Refinement - Prompt: `prompts/01-puzzle-refinement.md` - Output: `outputs/research_puzzle.md` - Inputs: `outputs/research_intake.md` - Gate: none | HiL: **HiL-1** - **EC mode:** also read the "Empirical-Companion Mode Addendum" at the end of the prompt file, and apply it. Additional input: `outputs/empirical_scope.md`. ### Stage 2 — Literature Positioning - Prompt: `prompts/02-literature-positioning.md` - Output: `outputs/literature_positioning.md` - Inputs: `outputs/research_puzzle.md` - Gate: **Gate 1** | HiL: **HiL-2** - **EC mode:** also read the "Empirical-Companion Mode Addendum" at the end of the prompt file, and apply it. **⚠️ MANDATORY: Web-verify every citation before writing it to `literature_positioning.md`.** For each paper identified in Stage 2, use WebSearch or WebFetch to confirm: 1. Author(s) and year are correct 2. Title is the actual published title (not a plausible-sounding variant) 3. Journal name, volume, issue, and page numbers are correct 4. The paper actually exists (search `"author year title site:scholar.google.com"` or similar) Mark each citation as one of: - **VERIFIED** — confirmed via web search (include the URL or source) - **UNVERIFIED** — could not confirm; flag explicitly and DO NOT include in any manuscript bibliography LLMs hallucinate plausible-sounding but nonexistent papers, especially for applied/empirical China literature. A citation that looks real is not the same as a citation that is real. Never include a citation in any output without web verification. ### Stage 2a — Empirical Reality Check / Institutional Context Check - Prompt: `prompts/02a-empirical-reality-check.md` - Output: `outputs/empirical_reality_check.md` - Inputs: `outputs/research_puzzle.md`, `outputs/literature_positioning.md` - Gate: **Gate 1b** (Reality Fit Gate — defined inside `prompts/02a-empirical-reality-check.md`) | HiL: none **Purpose:** Before committing to a model structure, verify that the real-world context described by the researcher matches the factual requirements of the proposed model family. Use web search to check market concentration data, institutional rules, and evidence for claimed group or regional differences. This stage does NOT build a model — it only checks that the model's implicit factual assumptions are not contradicted by publicly available evidence. **Gate 1b verdict logic:** - **PASS**: All key factual assumptions SUPPORTED or WEAKLY SUPPORTED → proceed to Stage 3. - **CONDITIONAL PASS (REFRAME)**: 1–2 assumptions UNSUPPORTED but not POTENTIALLY FALSE → proceed with a caveat: the paper must describe the setting as stylized, not claim to describe a specific real market. Document the reframing in `empirical_reality_check.md`. - **FAIL (REROUTE — Stage 1)**: Any assumption POTENTIALLY FALSE, or 3+ UNSUPPORTED → stop; researcher must restate the puzzle with a corrected or explicitly hypothetical setting. - **FAIL (REROUTE — Stage 3b)**: The proposed canonical model family is inconsistent with verified market structure → redirect Stage 3b to a different model family. **⚠️ If Gate 1b fails, do NOT proceed to Stage 3.** Present the gate failure in the standard format and wait for the researcher to decide: loop back to Stage 1, commit to a hypothetical/stylized framing, or redirect to an alternative model family. ### Stage 3 — Theory Persona Council - Prompt: `prompts/03-persona-council.md` - Output: `outputs/persona_council.md` - Inputs: `outputs/research_puzzle.md`, `outputs/literature_positioning.md`, `outputs/empirical_reality_check.md` - Council format: 5 personas, 2-round council — independent assessment (Round 1) followed by cross-review and synthesis (Round 2) - Gate: none | HiL: **HiL-3** - **EC mode:** also read the "Empirical-Companion Mode Addendum" at the end of the prompt file, and apply it. ### Stage 3b — Canonical Model Matching - Prompt: `prompts/03b-canonical-model-match.md` - Output: `outputs/canonical_model_match.md` - Inputs: `outputs/research_puzzle.md`, `outputs/literature_positioning.md`, `outputs/persona_council.md`, `model_library/` (all files) - Gate: **Gate 2b** (Canonical Fit) then **Gate 2c** (Theory Lineage) — run both sequentially | HiL: none → proceed to Stage 4 - **EC mode:** also read the "Empirical-Companion Mode Addendum" at the end of the prompt file, and apply it. Strictness is unchanged; the addendum adds an assessment of the researcher's stated model-family preference. - Note: if the research involves human capital, labor, automation, or AI-labor topics, the prompt explicitly requires checking `model_library/human_capital_and_labor/` - Note: if the research involves market structure, pricing, platforms, or entry/competition topics, check `model_library/io/` - Note: if the research involves trade patterns, trade liberalization, exporter behavior, or gains from trade, check `model_library/comparative-advantage-ricardian.md`, `model_library/heckscher-ohlin.md`, `model_library/new-trade-theory-krugman.md`, `model_library/melitz-firm-heterogeneity.md` - Note: if the research involves regional/spatial dynamics, internal migration, regional convergence, local labor market adjustment, or the dynamic effects of trade shocks across regions, check `model_library/dynamic-spatial-general-equilibrium.md` and `model_library/trade-labor-dynamics-china-shock.md` - Note: if the research involves admission cutoffs, threshold scores, exam ranks, school choice, or any centrally rationed assignment, check `model_library/matching-with-cutoffs.md` in addition to `model_library/matching-models.md` - Note: if the research involves job risk, workplace violence, hours, or any non-wage job attribute, check `model_library/human_capital_and_labor/compensating-differentials.md`; if wages in the setting are administratively set, that file's regulated-wage extension is the relevant part - Note: if the research involves entry into an occupation with a multi-year training pipeline (medicine, law, engineering, licensed trades), check `model_library/human_capital_and_labor/cobweb-supply-lags.md` for the training-lag dynamics before treating an entry decline as a permanent repricing ### Stage 4 — Model Primitives - Prompt: `prompts/04-model-primitives.md` - Output: `outputs/model_primitives.md` - Inputs: `outputs/research_puzzle.md`, `outputs/persona_council.md`, **`outputs/canonical_model_match.md`** (NEW — must use the handoff block) - Gate: **Gate 2** | HiL: **HiL-4 ★ HARD STOP** - **EC mode:** also read the "Empirical-Companion Mode Addendum" at the end of the prompt file, and apply it. It enables the Minimal Model Principle and requires two extra outputs: `outputs/minimality_check.md` and the draft of `outputs/empirical_theory_map.md` (see `prompts/ec-empirical-theory-map.md`). - Note: Stage 4 must explicitly adopt the "Inherit from the canonical model" elements listed in `canonical_model_match.md`; any deviation must be noted and justified ### Stage 5 — Assumption Audit - Prompt: `prompts/05-assumption-audit.md` - Output: `outputs/assumption_audit.md` - Inputs: `outputs/model_primitives.md` - Gate: none | HiL: none → proceed to Stage 6 - **EC mode:** also read the "Empirical-Companion Mode Addendum" at the end of the prompt file, and apply it. It adds the `ADDED-FOR-TARGET` tag and the no-assumption-laundering rule. ### Stage 6 — Proposition Generator - Prompt: `prompts/06-proposition-generator.md` - Output: `outputs/candidate_propositions.md` - Inputs: `outputs/model_primitives.md`, `outputs/assumption_audit.md` - Gate: **Gate 3** | HiL: **HiL-5** - **EC mode:** also read the "Empirical-Companion Mode Addendum" at the end of the prompt file, and apply it. It relaxes the required proposition types to one per target hypothesis, defers the rest to `outputs/scope_notes.md`, and completes `outputs/empirical_theory_map.md`. **Gate EC runs after Gate 3 and before HiL-5** (`prompts/gate-ec-empirical-alignment.md`). - ⚠️ Citations in the "Connection to Prior Literature" sections must be reused from the VERIFIED entries in `literature_positioning.md`. Any NEW citation introduced here requires its own web verification (same rule as Stage 2) before it is written to the file. ### Stage 7 — Proof Sketch - Prompt: `prompts/07-proof-sketch.md` - Output: `outputs/proof_sketches.md` - Inputs: `outputs/candidate_propositions.md`, `outputs/model_primitives.md`, `outputs/assumption_audit.md` - Gate: **Gate 4** | HiL: **HiL-N1** (Numerical Simulation Decision — always presented; Stage 7b runs only on explicit user opt-in) - **EC mode:** also read the "Empirical-Companion Mode Addendum" at the end of the prompt file, and apply it. It requires a per-hypothesis derivability verdict and the `TARGET HYPOTHESIS NOT DERIVED` block where a target cannot be established. Gate 4 gains check EC-D. ### Stage 7b — Numerical Simulation and Computational Illustration (OPTIONAL — USER-CONTROLLED) - Prompt: `prompts/07b-numerical-simulation.md` - Outputs: `outputs/numerical_simulation_decision.md` (always, once HiL-N1 is answered); `outputs/numerical_simulation_plan.md` + `outputs/parameter_definitions.md` (PLAN ONLY / CUSTOM / YES); `outputs/numerical_code/`, `outputs/numerical_results/`, `outputs/numerical_figures/`, `outputs/numerical_simulation_report.md` (only after HiL-N2 APPROVE PLAN) - Inputs: `outputs/candidate_propositions.md`, `outputs/proof_sketches.md`, `outputs/model_primitives.md`, `outputs/assumption_audit.md` - Gate: **Gate 4b** (only if code ran) | HiL: **HiL-N1** (entry decision), **HiL-N2** (★ execution hard stop), **HiL-N3** (results review) - **EC mode:** also read the "Empirical-Companion Mode Addendum" at the end of the prompt file, and apply it. It narrows the HiL-N1 *recommendation* to three triggers. The user-control rule is unchanged. **⚠️ This stage NEVER runs by default.** The pipeline must not decide on its own whether to simulate. Full branching logic: ``` Stage 7 + Gate 4 complete → present HiL-N1 (ask the user whether to run numerical simulation) NO → write numerical_simulation_decision.md → log: [STAGE 7b — Numerical Simulation] | SKIPPED BY USER → create NO other numerical artifacts (no code, no results, no placeholder or empty figures) → Stage 8 PLAN ONLY → write decision record + numerical_simulation_plan.md → execute NO code; claim NO numerical results → pause and wait for further user confirmation CUSTOM → collect user specifications (propositions, variables, baselines, ranges, axes, simulation types, figure formats, counterexample search) → write plan + parameter_definitions.md → HiL-N2 YES → write plan + parameter_definitions.md → HiL-N2 → HiL-N2: APPROVE PLAN required before ANY code execution (REVISE PARAMETERS / FIGURES / MODEL → update plan, re-present HiL-N2; CANCEL SIMULATION → log and proceed to Stage 8) → generate code → run simulation → save machine-readable CSV results → generate PNG and PDF figures → Gate 4b (Numerical Integrity Gate) → gates/gate-04b-numerical-integrity.md → HiL-N3 (human review of numerical results) → Stage 8 (with the numerical handoff block from numerical_simulation_report.md) ``` Log every decision: `[HiL-N1 — Numerical Simulation Decision] | researcher: — `, `[HiL-N2 — Simulation Plan Approval] | researcher: — `, `[GATE 4b — Numerical Integrity Gate] | — `, `[HiL-N3 — Numerical Results Review] | researcher: — `. **⚠️ Counterexample blocking rule:** if Gate 4b records a counterexample to a core proposition, the original unmodified proposition is BLOCKED from Stage 10 (`state.json` → `numerical_simulation.blocked_propositions`) until Stage 8 + HiL-6 resolve it and the proposition text is revised. ### Stage 8 — Counterexample Finder - Prompt: `prompts/08-counterexample-finder.md` - Output: `outputs/counterexamples_and_edge_cases.md` - Inputs: `outputs/candidate_propositions.md`, `outputs/proof_sketches.md`, `outputs/assumption_audit.md`; **plus, if Stage 7b ran:** `outputs/numerical_simulation_report.md` (the "Handoff to Stage 8" block) and `outputs/numerical_results/` - Gate: none | HiL: **HiL-6** - **EC mode:** also read the "Empirical-Companion Mode Addendum" at the end of the prompt file, and apply it. The full adversarial battery still runs; findings inside the declared empirical domain are gate-failing, findings outside it go to `outputs/scope_notes.md`. - Note: Stage 7b does not replace this stage. If numerical counterexamples or suspicious regions were handed off, Stage 8 must diagnose each one (coding error / numerical optimization error / parameter issue / assumption failure / claim failure / proposition-domain issue) and recommend the proposition's fate (retain / weaken / restrict to functional-form class / split into regimes / relabel as illustrative / drop) ### Stage 9 — Economic Interpretation - Prompt: `prompts/09-economic-interpretation.md` - Output: `outputs/economic_interpretation.md` - Inputs: `outputs/candidate_propositions.md`, `outputs/proof_sketches.md`, `outputs/counterexamples_and_edge_cases.md`, `outputs/model_primitives.md` - Gate: **Gate 5** | HiL: none → proceed to Stage 10 - **EC mode:** also read the "Empirical-Companion Mode Addendum" at the end of the prompt file, and apply it. - ⚠️ Same citation rule as Stage 6: only VERIFIED citations (from `literature_positioning.md` or freshly web-verified in this session) may appear in `economic_interpretation.md`. ### Stage 10 — Manuscript Skeleton - Prompt: `prompts/10-manuscript-skeleton.md` - Output: `outputs/manuscript_skeleton.md` - Inputs: ALL prior outputs in `outputs/` - Gate: **Gate 6** (Mathematical Review — runs during the Completion sequence, after `manuscript.tex` is written and before pdflatex; see Completion step 3c) | HiL: none → **PIPELINE COMPLETE** - **EC mode:** also read the "Empirical-Companion Mode Addendum" at the end of the prompt file, and apply it. It produces an applied-paper Conceptual Framework section (3.1 Economic Environment / 3.2 Model / 3.3 Predictions) with hypotheses generated from `outputs/empirical_theory_map.md`. **⚠️ Numerical content inclusion rule (applies to the skeleton, `manuscript.tex`, and the PDF).** Numerical results or figures from Stage 7b may enter the manuscript ONLY if the researcher explicitly selected `USE FIGURES IN MANUSCRIPT` (or `APPENDIX ONLY`, for the Appendix) at HiL-N3, AND all of: 1. code and parameters are saved under `numerical_code/` and `parameter_definitions.md`; 2. Gate 4b is not FAIL (CONDITIONAL PASS conditions resolved); 3. every included figure is fully reproducible from the scripts; 4. every included figure exists in the requested formats (both PNG and PDF by default — use the PDF in LaTeX, keep the PNG for README/slides); 5. every caption identifies the content as exactly one of: analytical result / numerical example / simulation result / computational illustration / parameter sweep / empirical calibration / counterexample; 6. relevant limitations are stated; 7. any detected counterexample is disclosed in the main text or Appendix. Prohibited manuscript language for numerical content: "we prove" for a numerical result; "generally" for a finite parameter grid; "robust" for a single baseline example; "calibrated" for illustrative parameter values; "causal" for a purely theoretical simulation; "unique" unless numerical AND analytical evidence both justify it. Any proposition listed in `state.json` → `numerical_simulation.blocked_propositions` must NOT appear in the manuscript in its original form — only the Stage-8/HiL-6-revised version may enter. **Demonstration-figure default:** when the researcher authorizes `USE FIGURES IN MANUSCRIPT`, include **1–2 demonstration figures** in the main text — the headline mechanism/welfare figure, plus at most one parameter-sweep or regime-map figure — in a short "Numerical Illustration" subsection near the results they illustrate. Embed the PDF versions via `graphicx`; each caption must carry the type label, the baseline parameter values, a "not a proof" qualifier where applicable, and a pointer to the reproducing scripts (`numerical_code/`). All other figures remain in the workspace (or Appendix if authorized). --- ## State Management Initialize `state.json` from `templates/state.json`. Update after every stage and gate. Key fields to maintain: - `mode` — `"theory-development"` (default) or `"empirical-companion"`; set once at initialization from the `## Mode Routing` resolution and never changed mid-run. A state file without this key is read as `"theory-development"`. - `current_stage` — integer 0–10; update after each stage starts. Stage 0-EC is recorded as `"0-EC"` in `completed_stages` and leaves `current_stage` at 0. - `stage_status` — `"in_progress"` | `"awaiting_hil"` | `"gate_failed"` | `"completed"` - `completed_stages` — append stage name on completion - `gate_results` — write `{"result": "PASS"|"FAIL", "severity": "...", "reason": "..."}` per gate - `human_decisions` — record researcher responses at each HiL (including `hil_n1`, `hil_n2`, `hil_n3` when Stage 7b is entered) - `caveats` — append when gate failure is overridden with caveat - `numerical_simulation` — Stage 7b state: `decision` (`"YES"|"NO"|"PLAN_ONLY"|"CUSTOM"|null`), `plan_approved` (bool), `executed` (bool), `gate_4b` (verdict or null), `results_review` (HiL-N3 selections), `figures_authorized_for_manuscript` (`"main_text"|"appendix_only"|"none"|null`), `blocked_propositions` (proposition IDs blocked from Stage 10 by the Gate 4b counterexample rule) - `empirical_companion` — `empirical-companion` mode state, inert in the default mode: `scope_locked` (bool), `scope_status` (`"LOCKED"|"REVISE"|null`), `target_hypotheses` (the H-labels from `empirical_scope.md`), `excluded_extensions`, `unmapped_propositions` (Gate EC check EC1), `underived_hypotheses` (Stage 7 / Gate 4 check EC-D) - `gate_results.gate_ec` — Gate EC verdict; stays `null` in `theory-development` mode - `finished` — set `true` when Stage 10 completes --- ## Resume Protocol If invoked with `--resume `: 1. Read `state.json` from that workspace, including `mode`. A state file with no `mode` key is `theory-development`. The resumed mode governs the rest of the run; a mode token in the resume invocation is ignored. 2. Check `current_stage` and `stage_status` 3. If `stage_status == "awaiting_hil"`: re-present the HiL checkpoint and wait 4. If `stage_status == "gate_failed"`: re-present the gate failure and ask researcher to decide 5. If `stage_status == "in_progress"`: re-run the current stage from the start (prior output may be incomplete) 6. Continue the pipeline from the identified stage --- ## Error Handling - **Missing input file:** Run the missing stage first, then continue - **Completely ambiguous hypothesis:** Ask ONE clarifying question in Stage 0 before proceeding - **Gate fails twice on same stage:** Present failure, allow researcher to proceed with caveat regardless - **Model incoherence unresolvable after two Stage 4 attempts:** Require researcher to manually provide a model sketch before continuing --- ## Completion When Stage 10 completes: 1. Set `"finished": true` in `state.json` 2. **⚠️ REFERENCE VERIFICATION GATE — mandatory before writing any bibliography.** This step must be completed before writing `manuscript.tex`. It cannot be skipped. a. Collect every citation you intend to include in the manuscript bibliography. b. For each citation, use WebSearch to verify it exists. Specifically confirm: - The exact title (not a plausible paraphrase) - Author names and year - Journal/publisher, volume, issue, page numbers c. Classify each citation: - **VERIFIED** — web search returned a matching result (record the source URL in `outputs/references_verified.md`) - **HALLUCINATED / UNCERTAIN** — web search found no matching result, or found a different paper with similar details d. **Only include VERIFIED citations in the manuscript bibliography.** Remove all UNCERTAIN or unverifiable ones, even if they look plausible. A citation that cannot be confirmed by web search does not belong in the paper. e. Write `outputs/references_verified.md` listing every proposed citation, its verification status, and the confirmation source or reason for exclusion. **Why this matters:** LLMs generate convincing-looking but nonexistent citations, especially for applied China literature and niche empirical papers. Author names, journal names, and years are often correct while the title, volume, or page numbers are fabricated. The only safe check is an external web search — internal confidence is not sufficient evidence. 3. **Generate the manuscript PDF** by writing a complete LaTeX file and compiling with pdflatex: a. **Title**: Use the format `": A Theoretical Framework"`. The description should be one short phrase (≤ 8 words) that names the core question, not the key finding. Example: "Education Investment under China's Hukou System: A Theoretical Framework". Do NOT use a long descriptive title that will exceed 2 lines. b. **Write `outputs/manuscript.tex`** as a complete academic paper (not a skeleton). Follow the style of the reference PDF (`260311_genetic_diversity_skill_formation_model_v3.pdf`) exactly: ```latex \documentclass[12pt]{article} \usepackage[margin=1.2in]{geometry} \usepackage{amsmath,amsthm,amssymb} \usepackage{microtype} \usepackage[authoryear,round]{natbib} \usepackage{xcolor} \definecolor{linkgreen}{RGB}{0,120,100} \usepackage[colorlinks=true,linkcolor=linkgreen,citecolor=linkgreen,urlcolor=linkgreen]{hyperref} % Use \Large (not default \LARGE) so title fits in 2 lines \makeatletter \renewcommand{\maketitle}{% \begin{center}% {\Large\bfseries \@title \par}% \vskip 1.5em% {\normalsize \@author \par}% \vskip 0.8em% {\normalsize \@date}% \end{center}% \vskip 2em% } \makeatother \theoremstyle{plain} \newtheorem{proposition}{Proposition} \newtheorem{lemma}{Lemma} \newtheorem{corollary}{Corollary} \theoremstyle{definition} \newtheorem{assumption}{Assumption} \newtheorem{definition}{Definition} \theoremstyle{remark} \newtheorem{remark}{Remark} \title{: A Theoretical Framework} \author{% \texttt{pAI-Econ-claude} (\texttt{theoretical-economics-claude-skill})\\[4pt] \small\url{https://github.com/maxwell2732/pAI-Econ-claude}\\[2pt] \small % } \date{Draft: } ``` **⚠️ Model attribution:** Replace `` with the name of the Claude model actually running this pipeline session (e.g., "Claude Fable 5", "Claude Opus 4.8"), as stated in your own system context. NEVER hardcode or copy a model name from an earlier project's manuscript — a paper generated by one model must not be attributed to another. The paper body should contain real academic prose: Introduction, Model (with subsections), Results (Propositions/Lemmas with proofs or proof sketches), Comparative Statics, Welfare, Boundary Cases, Testable Predictions, and a `thebibliography` section. Do NOT write a skeleton outline or include meta-commentary. See `feedback-pdf-style.md` in project memory for the complete style rules. c. **⚠️ GATE 6 — MATHEMATICAL REVIEW GATE (mandatory before compiling).** Read `prompts/gate-06-math-review.md` and review `manuscript.tex` top to bottom: - **Statement classification**: equilibrium conditions, FOCs, definitions, and identities must NOT sit in `proposition`/`lemma`/`corollary` environments; every theorem-like environment must contain the kind of statement its label claims. - **Independent re-derivation**: re-derive every displayed derivation (FOCs, closed forms, comparative-statics signs) from `model_primitives.md` WITHOUT consulting the manuscript's steps, then compare term by term. - **Notation consistency**, **statement–proof match**, and **domain/boundary sanity**. Fix TYPO-LEVEL and LOW errors directly and back-propagate the fixes to `manuscript_skeleton.md`, `candidate_propositions.md`, and `proof_sketches.md`. A SUBSTANTIVE error (wrong sign or content under re-derivation, proof that fails to establish its claim) is a gate FAIL: apply the standard gate-failure protocol and do NOT compile. Write the verdict to `gates/gate-06-math-review.md`, log it in `logs/stage-log.md`, and record `gate_results.gate_6` in `state.json`. Compile only on PASS or PASS WITH CORRECTIONS. d. **Compile** with pdflatex (twice for cross-references): ``` pdflatex -interaction=nonstopmode /outputs/manuscript.tex pdflatex -interaction=nonstopmode /outputs/manuscript.tex ``` Check the `.log` file for lines beginning with `!` (fatal errors). Warnings about rerunning are expected on the first pass and safe to ignore. e. If compilation succeeds, confirm `outputs/manuscript.pdf` exists and record `"pdf_generation": "success"` in `state.json`. f. If pdflatex fails, record `"pdf_generation": "failed"` in `state.json`, print the error lines from the `.log` file, and note what the researcher must fix manually. 4. Print completion summary: ``` ================================================================ [COMPLETE] Theoretical Economics Pipeline Finished ================================================================ Workspace: Exploration/Project_NNN_/ Mode: [theory-development / empirical-companion] Stages completed: 13 (0–10 + 2a + 3b) [14 if Stage 7b ran] [+1 if Stage 0-EC ran] Gate results: Gate 1 (Novelty Risk): [PASS / FAIL+caveat] Gate 1b (Reality Fit): [PASS / REFRAME / FAIL+caveat] Gate 2b (Canonical Fit): [PASS / FAIL+caveat] Gate 2c (Theory Lineage): [PASS / FAIL+caveat] Gate 2 (Model Coherence): [PASS / FAIL+caveat] Gate 3 (Non-triviality): [PASS / FAIL+caveat] Gate 4 (Proof Integrity): [PASS / FAIL+caveat] Gate 4b (Numerical Integrity): [PASS / CONDITIONAL / FAIL+caveat / NOT RUN — user skipped 7b] Gate 5 (Economic Meaning): [PASS / FAIL+caveat] Gate 6 (Math Review): [PASS / PASS WITH CORRECTIONS / FAIL+caveat] Gate EC (Empirical Alignment): [PASS / CONDITIONAL PASS / FAIL+caveat / NOT RUN — theory-development mode] Output files: [if empirical-companion mode:] outputs/empirical_scope.md ← Stage 0-EC scope contract outputs/minimality_check.md ← Stage 4/6 outputs/empirical_theory_map.md ← Stage 4/6 outputs/scope_notes.md ← Stages 4–8, deferred findings outputs/research_puzzle.md outputs/literature_positioning.md outputs/empirical_reality_check.md outputs/persona_council.md outputs/canonical_model_match.md outputs/model_primitives.md outputs/assumption_audit.md outputs/candidate_propositions.md outputs/proof_sketches.md [if Stage 7b ran:] outputs/numerical_simulation_decision.md outputs/numerical_simulation_plan.md outputs/parameter_definitions.md outputs/numerical_simulation_report.md outputs/numerical_code/ · numerical_results/ · numerical_figures/ (PNG + PDF) outputs/counterexamples_and_edge_cases.md outputs/economic_interpretation.md outputs/manuscript_skeleton.md outputs/manuscript.tex ← LaTeX source (pdflatex) outputs/manuscript.pdf ← Academic PDF (Computer Modern) Suggested next steps: - Open manuscript.pdf to review the theoretical framework paper - Formalize proof sketches into complete proofs - Expand comparative statics with numerical calibration - Run literature search using literature_positioning.md keywords - Extend manuscript.tex with empirical motivation or extensions ================================================================ ``` --- ## Implementation Notes - Always use absolute paths for file reads and writes - Print stage banners clearly so the researcher can track progress - Never modify `initial_context/hypothesis.md` after it is written - When in doubt about a stage output's quality, note concerns in the output file rather than silently lowering quality - All output files are in Markdown; the manuscript skeleton may contain LaTeX fragments - The `prompts/` and `templates/` directory paths are relative to the directory containing this SKILL.md file - All project workspaces live under `Exploration/` in the repo root, named `Project_NNN_/`. Never write project files to the repo root directly. --- ## Attribution **theoretical-economics-claude-skill** is developed by: - **Chen Zhu** — China Agricultural University (CAU) - **Xiaolu Wang** — China Agricultural University (CAU) - **Weilong Zhang** — University of Cambridge Based on **pAI/MSc** by Mahmoud Abdelmoneum, Pierfrancesco Beneventano, and Tomaso Poggio (MIT + Perseus Labs). Technical report: https://dspace.mit.edu/handle/1721.1/165377 Repository: **pAI-Econ-claude** (MIT License)