Back to search
theoretical-economics-claude-skill
SkillWorks with Claude CodeGitHub
"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."
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/maxwell2732--pai-econ-claude)HTML
<a href="/listings/maxwell2732--pai-econ-claude"><img src="/api/listings/maxwell2732--pai-econ-claude/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
git clone https://github.com/maxwell2732/pAI-Econ-claude.git cd pAI-Econ-claude
在该目录下打开 Claude Code,slash command 即自动可用:
/theoretical-economics-claude-skill "你的理论经济学研究想法"
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 1,238 lines
- ---
- 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) ║
- ║ 10 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 <workspace>`: 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_<ModelAbbrev>/` 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_<ModelAbbrev>/`.
- 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_<ModelAbbrev>/ ← e.g. Project_003_RationalInattention
- ├── state.json
- ├── verification_record.json # Per-claim status and evidence (from Stage 6)
- ├── verification/
- │ ├── derivations/ # One file per re-derived claim: the working
- │ ├── numerical/ # Optimality systems; independent reimplementations
- │ └── counterexamples/ # Search scripts and the instances found
- ├── 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-04r-revision-regate.md # After HiL-6 (revised claims only)
- │ ├── 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 | **Gate 4R** (after HiL-6, on revised claims only) | **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
- Ten 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; Gate 4R runs after HiL-6 and costs nothing when no claim text changed). 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. This does not apply to a non-downgradable finding; see the table in `### Non-downgradable findings` below.
- ---
- ### Objective FAIL triggers
- A gate verdict is FAIL whenever any trigger below fires, independently of any WARNING-count arithmetic in that gate's own verdict rules. WARNING counts remain as a secondary path to CONDITIONAL PASS. **No verdict above FAIL may be issued while a trigger is live.**
- | ID | Trigger | Gates |
- |----|---------|-------|
- | FT-1 | A claim's Entailment Ledger returns `FAIL` on any link | 3, 4, 4R, 6 |
- | FT-2 | A claim is contradicted by an expression the gate itself verified | 4, 4R, 6 |
- | FT-3 | A valid counterexample satisfying the claim's stated hypotheses | 4, 4b, 4R, 6 |
- | FT-4 | `assumptions.satisfiability == "INFEASIBLE_AT_STATED_POINT"` for a claim in use | 3, 4, 4R, 6 |
- | FT-5 | `assumptions.undeclared_but_used` non-empty for a CORE claim (assumption laundering) | 4, 4R |
- | FT-6 | A `MISSING` support-checklist item that the claim's conclusion depends on | 3, 4, 4R, 6 |
- | FT-7 | Constraint-status disagreement between the verifier's and the author's implementation at any grid point | 4b |
- | FT-8 | `usability_ratio < 0.5`, or any grid exclusion with `derived_from_model: false` | 4b |
- | FT-9 | `independence_grade` I3 or I4 offered as evidence for a `VERIFIED` status | 4, 4b, 4R, 6 |
- | FT-10 | A `VERIFIED` or `CONDITIONALLY VALID` claim depends on a `CONJECTURE` | 4, 4R, 6 |
- | FT-11 | A proof establishes a weaker claim than the statement asserts, strictness included | 6 |
- | FT-12 | A claim whose `claim_text_sha256` changed since its last gate decision still carries a status other than `NOT VERIFIED` | 4, 4R, 6 |
- The ledger, the support checklist, and the satisfiability procedure are defined in `prompts/entailment-ledger.md`. The independence grades and grid requirements are in `prompts/proof-code-independence.md`. Claim statuses are in `prompts/verification-record.md`.
- ### Non-downgradable findings
- > A finding in a non-downgradable class may not be reclassified to a lower severity by the gate that found it, may not be resolved by `PROCEED WITH CAVEAT` alone, and may not reach the manuscript as an unqualified claim.
- | Class | Covers | Permitted resolutions |
- |-------|--------|----------------------|
- | **ND-1** Mathematical contradiction | FT-2 | correct the claim; withdraw it; or restate it as a `CONJECTURE` in a remark with the contradiction disclosed |
- | **ND-2** Valid counterexample | FT-3 | narrow the hypotheses to exclude the instance, with the narrowing audited; weaken the claim; split into regimes; drop it. Each produces a **new claim ID** at `NOT VERIFIED`. |
- | **ND-3** Incorrect constraint classification | FT-7 | fix the implementation and re-run. Every result derived from the defective classification is invalidated and re-derived. |
- | **ND-4** Missing load-bearing proof | a CORE claim at `NOT VERIFIED` entering the manuscript as a proposition | prove it; weaken it to what is proved; relabel as a `CONJECTURE` in a remark |
- | **ND-5** Infeasible hypothesis set | FT-4 | decompose the compound assumption and apply each clause where it holds |
- The researcher keeps final authority over which resolution is taken. What the class removes is the option of the finding disappearing: for a non-downgradable finding, `PROCEED WITH CAVEAT` is available only in the variant that **discloses the finding in the manuscript itself**, at the affected result, as a footnote or a stated limitation.
- ### Recording a downgrade
- Where a gate judges that a live FAIL trigger should not produce a FAIL, and the finding's class is downgradable:
- 1. Record the trigger by name in `verification_record.json → gate_decision.fail_conditions_hit`. **This field is filled whether or not a downgrade follows.**
- 2. Record `gate_decision.downgrades` with `from`, `to`, `rationale`, `class`, and `researcher_approved: false`.
- 3. Present this line in the gate output and at the next human checkpoint:
- ```
- ⚠️ FAIL CONDITION HIT AND DOWNGRADED
- Trigger: [FT-n] — [one-line description]
- Downgrade: FAIL → [severity]
- Reason: [the gate's rationale]
- Affected: [claim IDs]
- To accept the downgrade, type: APPROVE DOWNGRADE
- To treat it as a FAIL, type: REVERSE DOWNGRADE
- ```
- 4. `researcher_approved` stays `false` until the researcher answers. **An unapproved downgrade blocks manuscript inclusion of the affected claim.**
- A gate keeps its mathematical judgment and loses the ability to exercise it invisibly.
- ### Open obligations
- Every WARNING, every ledger `GAP`, and every condition a gate attaches to a CONDITIONAL PASS is written to `verification_record.json → unresolved_issues` with a `discharge_condition` and `blocks_manuscript`.
- **Every gate, before evaluating its own checks, reads every OPEN obligation on every claim in scope and records for each either `DISCHARGED` with an evidence path or `STILL OPEN`.** A gate may not pass with an obligation silently carried forward. A remedy that was applied is not thereby discharged: the discharge requires evidence that the remedy closed the defect the obligation was raised against.
- ### Two additional HARD STOPs
- | Trigger | Behavior |
- |---------|----------|
- | Any claim reaches `INVALID` | **HARD STOP** at the gate or stage that found it. Present the error, the claim, every downstream claim from `depends_on`, and the ND-class resolutions. No further stage runs until the researcher chooses. |
- | A CORE claim is at `NOT VERIFIED` when Stage 10 begins | **HARD STOP** before `manuscript.tex` is written. See Completion step 2b. |
- | 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) |
- | 4R | Revision Re-gate | `prompts/gate-04r-revision-regate.md` | HiL-6, before Stage 9 (revised claims only) | Stage 8 (the resolution was wrong) or Stage 6 (the claim needs restating) |
- | 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 4R scope:** Gate 4R runs Gate 4's Checks 1, 3, 7 and 8 on **changed claim text only**, plus a check that the counterexample a revision was meant to exclude is actually excluded by the new hypotheses. Its scope list is every claim whose `claim_text_sha256` differs from the value at its last gate decision, every claim created by a weaken / narrow / split / relabel resolution, and every claim depending on one of those. With an empty scope list it records `NOT RUN — no revised claims` and costs nothing. It has no CONDITIONAL PASS. It exists because a claim rewritten at Stage 8 or HiL-6 previously reached `manuscript.tex` with Gate 6 as its first reader, which is the last gate in the pipeline. See `prompts/gate-04r-revision-regate.md`.
- **Gate 6 correction exception:** Gate 6 checks objective mathematics (statement classification, independent re-derivation, notation, statement–proof match, domain sanity, entailment). 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.
- **Limits on that exception.** The self-correction authority covers notation, labels, LaTeX, and algebra slips that change no claim's direction. It does NOT extend to:
- - any change to a claim's hypotheses, quantifiers, or strictness;
- - any reclassification of a statement that reduces the count of genuine CORE results;
- - any edit that would resolve an Entailment Ledger `FAIL` or `GAP`.
- Those are SUBSTANTIVE by definition and go to the researcher. Gate 6 is the last reviewer in the pipeline and it may edit the manuscript, so without this limit it could rewrite the claims it is reviewing.
- **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 / CONDITIONAL PASS / FAIL — one-line reason]
- Candidate propositions:
- [P_1] [Proposition type] — [one-line statement]
- [P_2] [Proposition type] — [one-line statement]
- ...
- VERIFICATION STATUS
- ID Role Status Indep. Entailment Open obl.
- [P_1] CORE NOT VERIFIED — 9 OK 0
- [P_2] CORE NOT VERIFIED — 7 OK, 2 GAP 1 ← L5 factor positivity
- ...
- Claims with an Entailment FAIL: [n] ([IDs])
- Claims with a MISSING support item: [n] ([ID + item])
- FAIL conditions hit and downgraded: [n]
- Open obligations from earlier gates: [n] ([n] blocking the manuscript)
- Checks not performed: [named, e.g. "counterexample search (all
- claims, deferred to Stage 8)"]
- 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
- SHOW EVIDENCE [P_n] — Print the verification record and any derivation for one claim
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- ```
- **The evidence block is generated from `verification_record.json`, never from memory.** Three rules govern it, and they apply at every checkpoint that renders it (HiL-5, HiL-N3, HiL-6):
- 1. **An empty column is printed as empty.** `—` means the field is null, which is information. A skipped check may not be rendered as a blank the eye reads as fine.
- 2. **`Checks not performed` is a required line.** At HiL-5 the honest value names the counterexample search and anything the gate deferred. "none" is a claim, so write it only when every applicable check ran.
- 3. **`SHOW EVIDENCE [P_n]` prints that claim's record entry and its derivation file**, then re-presents the checkpoint. It is read-only and repeatable, and it exists so a researcher can audit one claim without reading every gate file.
- At HiL-5 every claim is at `NOT VERIFIED` and the `Indep.` column is empty for all of them, because no gate has yet seen a proof. That is the correct display and it is worth reading as the baseline: a status at this checkpoint carries no evidence yet.
- **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]
- VERIFICATION STATUS
- ID Role Status Indep. Entailment Open obl.
- [P_id] CORE NOT VERIFIED — 9 OK 0
- Claims with an Entailment FAIL: [n]
- Claims with a MISSING support item: [n]
- FAIL conditions hit and downgraded: [n]
- Open obligations from earlier gates: [n]
- Underived target hypotheses: [n] ([H labels])
- Checks not performed: [named]
- 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)
- SHOW EVIDENCE [P_n] — Print the verification record for one claim
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- ```
- Log as `[HiL-5 — Empirical Companion Checkpoint] <ISO timestamp> | researcher: <choice> — <notes>`. 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"]
- VERIFICATION STATUS (numerical)
- ID Role Status Indep. Usable grid Regimes tested Open obl.
- [P_n] CORE NUMERICALLY SUPPORTED I1 0.86 6 of 6 0
- [P_m] CORE NOT VERIFIED I3 0.049 3 of 6 2
- Epistemic label per result: [label per claim]
- Constraint-status agreement: [points compared, disagreements]
- Grid exclusions not derived from model: [n]
- FAIL conditions hit and downgraded: [n]
- Checks not performed: [named, e.g. "cross-validation against a
- second solver (not performed)"]
- 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] ...
- VERIFICATION STATUS
- ID Role Status Indep. Entailment Search Open obl.
- [P_n] CORE INVALID I1 1 FAIL (L3) FOUND 1
- [P_m] CORE NOT VERIFIED I1 9 OK NONE FOUND 0
- [P_k] CORE NOT VERIFIED — 9 OK NOT PERFORMED 0
- CORE claims with SEARCH NOT PERFORMED: [n] ([IDs]) — each capped below VERIFIED
- Claims at INVALID: [n] ([IDs]) — HARD STOP applies
- Open obligations: [n] ([n] blocking the manuscript)
- FAIL conditions hit and downgraded: [n]
- Checks not performed: [named]
- 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
- SHOW EVIDENCE [P_n] — Print the verification record, the search instance,
- and any derivation for one claim
- [Researcher specifies decisions per counterexample]
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- ```
- **Every resolution chosen here produces a revised claim, and a revised claim is a new claim.** State plainly at this checkpoint that `MODIFY ASSUMPTION`, `WEAKEN CLAIM` and a split each create a new ID at `NOT VERIFIED`, that nothing verified about the old text carries forward, and that **Gate 4R runs immediately after this checkpoint** on exactly those claims. The researcher is choosing a resolution and a re-check, so the cost is visible before the choice.
- ---
- ## 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/<filename>.md`
- 6. Append a structured entry to `logs/stage-log.md`:
- `[STAGE N — Stage Name] <ISO timestamp> | completed`
- 7. Update `state.json`: set `current_stage`, append to `completed_stages`, update `last_checkpoint`
- 7b. If the stage writes claim-level fields (Stages 6, 7, 7b, 8), update `verification_record.json` per `prompts/verification-record.md`. Stage 6 creates the entries; later stages amend them. A stage never raises a claim's `proof_status`.
- 8. If a gate follows: **first** read every OPEN obligation in `verification_record.json → unresolved_issues` for the claims in scope and record each as `DISCHARGED` with an evidence path or `STILL OPEN`. Then read the gate prompt file, evaluate the output, write the gate result to the matching file under `gates/` (see the Workspace Layout for exact filenames), and write `proof_status`, `entailment_ledger`, `support_checklist` and `gate_decision` back to `verification_record.json`.
- Then append to `logs/stage-log.md`, where `<id>` is the gate id (1, 1b, 2b, 2c, 2, 3, 4, 4b, 4R, 5, 6, or EC):
- - On pass: `[GATE <id> — Gate Name] <ISO timestamp> | PASS`
- - On fail: `[GATE <id> — Gate Name] <ISO timestamp> | FAIL [SEVERITY] — <one-line reason>`
- After the researcher decides, append the decision:
- - `[GATE <id> — Gate Name] <ISO timestamp> | researcher: LOOP BACK TO STAGE X`
- - `[GATE <id> — Gate Name] <ISO timestamp> | researcher: PROCEED WITH CAVEAT — <note or "no note">`
- 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] <ISO timestamp> | researcher: <choice> — <notes or "no notes">`
- 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] <ISO timestamp> | completed — scope <LOCKED|REVISE>, <n> 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**
- - **Initializes `verification_record.json`** from `templates/verification_record.json`: one entry per labelled statement, each at `proof_status: "NOT VERIFIED"`, with `role`, `tier`, `depends_on`, `source_files`, and the `assumptions` ledger (`declared`, `used`, `required_for_strength`, `undeclared_but_used`, `declared_but_unused`). See `prompts/verification-record.md`. `required_for_strength` is where a strict claim's real requirements are recorded, so fill it from the claim's own wording rather than from the assumption list.
- - **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)
- - Where this stage re-derives a load-bearing relation, write the working to `verification/derivations/<claim_id>.md` and record the path in `verification_record.json → independent_derivation`. A match/no-match table is not evidence; the derivation file holds the working so a third party can audit it.
- - **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)
- - **⚠️ Read `prompts/proof-code-independence.md` in full before writing any code.** Before implementation, derive an optimality system per optimization problem **and per model variant** into `verification/numerical/<variant>_optimality.md`, including the binding condition for every constraint and every feasibility bound. A variant's binding condition may never be inherited from another variant. Record `independence_grade`, `shared_from_author`, the regime matrix, and the grid honesty block in `verification_record.json`.
- - **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] <ts> | 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] <ts> | researcher: <YES/NO/PLAN ONLY/CUSTOM> — <notes>`, `[HiL-N2 — Simulation Plan Approval] <ts> | researcher: <choice> — <notes>`, `[GATE 4b — Numerical Integrity Gate] <ts> | <verdict> — <reason>`, `[HiL-N3 — Numerical Results Review] <ts> | researcher: <choices> — <notes>`.
- **⚠️ 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: **Gate 4R** (after HiL-6, on revised claims only) | HiL: **HiL-6**
- - Write one `counterexample_tests` entry per claim to `verification_record.json`, each `COUNTEREXAMPLE FOUND` (with the instance and a check that every stated hypothesis holds at it), `NO COUNTEREXAMPLE FOUND` (with the search space stated), or `SEARCH NOT PERFORMED` (with a reason). A skipped search is recorded rather than omitted. Direct the attempts at whatever the Entailment Ledger flagged: an L3 `FAIL` means construct the equality configuration; an L5 `FAIL` means set the factor to zero; a `MISSING` S1 means place a zero-density interval at the threshold; a `MISSING` S2 means insert a gap in the support.
- - **⚠️ Every CORE claim gets one executable search attempt**, numeric (a script under `verification/counterexamples/<claim_id>.py` that instantiates the model, evaluates every stated hypothesis at the instance, and evaluates the conclusion) or symbolic (a written construction with the same three parts). Prose reasoning about whether a counterexample might exist does not satisfy it. The attempt is aimed at the flag the ledger raised, per the mapping table in the prompt file. `SEARCH NOT PERFORMED` on a CORE claim is a permitted and recorded outcome, and it caps that claim at `CONDITIONALLY VALID` at every later gate.
- - Verification code written here may not import from `outputs/numerical_code/`; see `prompts/proof-code-independence.md`.
- - **⚠️ A claim this stage rewrites is a new claim.** Set a new ID, status `NOT VERIFIED`, and a fresh `claim_text_sha256`. A split proposition yields one claim per regime. The old claim keeps its own status and stops being used. A rewritten claim carries no verification forward from the text it replaced, and nothing between here and the manuscript re-checks it, so state its evidence gap plainly at 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)
- ### Gate 4R — Revision Re-gate (after HiL-6, before Stage 9)
- - Prompt: `prompts/gate-04r-revision-regate.md`
- - Output: `gates/gate-04r-revision-regate.md`
- - Runs on revised claims only: every claim whose `claim_text_sha256` changed since its last gate decision, every claim created by a HiL-6 or HiL-N3 resolution, and every claim depending on one of those
- - With an empty scope list, record `NOT RUN — no revised claims` and continue. Do not re-check claims whose text is unchanged.
- - Verdict is PASS or FAIL. On FAIL the loopback is Stage 8 (the resolution was wrong) or Stage 6 (the claim needs restating from the model)
- - Record the verdict in `state.json → gate_results.gate_4r` and the per-claim statuses in `verification_record.json`
- ### 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`
- - Entry condition: **Gate 4R is not FAIL.** A claim still at `INVALID` stops the pipeline here under the HARD STOP rule
- - 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.
- **⚠️ Claim status inclusion rule (applies to the skeleton, `manuscript.tex`, and the PDF).** Read `verification_record.json` and honour these three rules, which are checked again at the Completion step 1b hard stop:
- 1. A claim at `VERIFIED` or `CONDITIONALLY VALID` may appear in a `proposition`, `lemma`, `theorem`, or `corollary` environment. A `CONDITIONALLY VALID` claim appears with its `conditions` stated in the statement itself.
- 2. A claim at `NOT VERIFIED` may appear only as a labelled conjecture, in a `remark` or in running prose, under the word "conjecture". It may not sit in a theorem-like environment, and no `VERIFIED` or `CONDITIONALLY VALID` claim may depend on it.
- 3. A claim at `INVALID` may not appear.
- A `NUMERICALLY SUPPORTED` label accompanies its claim wherever that claim appears, together with the grid and the usability ratio. This rule is the reason an exploratory conjecture need not be deleted: it survives, marked, and nothing provable is allowed to rest on it.
- **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.
- **Two state files.** `state.json` holds pipeline position and researcher decisions. `verification_record.json` holds per-claim verification evidence and status; it is initialized from `templates/verification_record.json` at Stage 6 and is defined in `prompts/verification-record.md`. `state.json → active_propositions` stays a list of claim IDs and indexes into the record. A workspace with no `verification_record.json` is read as every claim at `NOT VERIFIED`, so `--resume` on a workspace created before v1.5.0 continues to work.
- 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"`.
- - `skill_version`, `skill_commit` — the skill release and the git short hash at initialization, so a workspace can be attributed to the prompt revision that produced it. Obtain the hash with `git rev-parse --short HEAD` in the repo root; write `"unknown"` if unavailable.
- - `verification_record` — relative path to the claim record, normally `"verification_record.json"`.
- - `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
- - `gate_results.gate_4r` — Gate 4R verdict, one of `"PASS"`, `"FAIL"`, or `"NOT RUN — no revised claims"`. A state file without this key reads as `null`, and a resumed pre-v1.5.0 workspace that passed HiL-6 runs Gate 4R on its scope list before Stage 9
- - `finished` — set `true` when Stage 10 completes
- ---
- ## Resume Protocol
- If invoked with `--resume <workspace_path>`:
- 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`
- 1b. **⚠️ CLAIM STATUS HARD STOP — mandatory before `manuscript.tex` is written.**
- Read `verification_record.json` and compute three counts:
- - CORE claims at `NOT VERIFIED`
- - claims at `INVALID`
- - OPEN obligations with `blocks_manuscript: true`
- If all three are zero, continue to step 2. Otherwise **stop and present**:
- ```
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- ★ HARD STOP | Claim Status Before Manuscript
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- CORE claims at NOT VERIFIED entering the manuscript: [n]
- [P_id] — [what is missing: which ledger link, which support item, which search]
- Claims at INVALID: [n]
- [P_id] — [the error or the counterexample]
- Open obligations blocking: [n]
- [OBL-id] — [discharge condition]
- Unapproved downgrades: [n]
- Gate 4R: [PASS / FAIL / NOT RUN — no revised claims]
- CORE claims with SEARCH NOT PERFORMED against current text: [n]
- Checks not performed: [named]
- A claim at NOT VERIFIED may not appear in a proposition, lemma, theorem or
- corollary environment. A claim at INVALID may not appear at all.
- For each, please choose:
- PROVE [P_n] — Loop back to Stage 7; I will attempt the proof
- WEAKEN [P_n] — Reduce the claim to what is established; specify or let me propose
- CONJECTURE [P_n] — Keep it as a labelled conjecture in a remark or in prose
- DROP [P_n] — Remove it from the manuscript
- DISCLOSE [P_n] — Keep the claim and state the gap in the manuscript at that result
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- ```
- Record each decision in `logs/stage-log.md` and in `verification_record.json`. `DISCLOSE` is the `PROCEED WITH CAVEAT` variant required for a non-downgradable finding, and the disclosure must appear in the manuscript at the affected result.
- 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 `"<brief description of the research problem>: 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{<Brief problem description>: 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 <ACTUAL MODEL NAME>%
- }
- \date{Draft: <Month DD, YYYY>}
- ```
- **⚠️ Model attribution:** Replace `<ACTUAL MODEL NAME>` 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 <WORKSPACE>/outputs/manuscript.tex
- pdflatex -interaction=nonstopmode <WORKSPACE>/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_<ModelAbbrev>/
- 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 4R (Revision Re-gate): [PASS / FAIL+caveat / NOT RUN — no revised claims]
- 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_<ModelAbbrev>/`. 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)
README.md · README · 1,059 lines
- <a href="https://doi.org/10.5281/zenodo.20686025"><img src="https://zenodo.org/badge/1268830527.svg" alt="DOI"></a>
- # pAI-Econ-claude
- <p align="center">
- <img alt="Status" src="https://img.shields.io/badge/status-theory--harness-blue">
- <img alt="Claude Code" src="https://img.shields.io/badge/Claude_Code-skill-blueviolet">
- <img alt="Domain" src="https://img.shields.io/badge/domain-theoretical--economics-0A66C2">
- <img alt="Human in the Loop" src="https://img.shields.io/badge/human--in--the--loop-required-orange">
- <img alt="License" src="https://img.shields.io/badge/license-MIT-lightgrey">
- </p>
- <p align="center">
- <b>一个连接经济学实证发现与理论建模的 Claude Code Skill</b><br>
- pAI-Econ-claude 并不试图替代理论经济学家的原创工作,而是帮助实证研究者把经验现象、机制直觉和实证发现转化为更清晰的理论问题、经典模型参照、可检验命题和可审计的研究框架。
- </p>
- <p align="center">
- <a href="./README_EN.md">English Version</a> ·
- <a href="#快速开始">快速开始</a> ·
- <a href="#运行模式">运行模式</a> ·
- <a href="#使用场景">使用场景</a> ·
- <a href="#理论模型库">理论模型库</a> ·
- <a href="#工作流">工作流</a>
- </p>
- > pAI stands for principal Agentic Investigator (Abdelmoneum, Beneventano, & Poggio, 2026).
- ---
- ## 作者与更新
- **作者:**
- Chen Zhu / 朱晨(China Agricultural University | 遗传社科研究)
- Xiaolu Wang / 王晓璐(China Agricultural University)
- Weilong Zhang / 章维龙(University of Cambridge)
- **最后更新:** 2026 年 11 月 16 日
- **v1.5.0 — 可靠性 bug 修复。** 修复流水线只校验推导、不校验「断言是否由推导推出」的缺陷。新增三个共享检查模块(蕴含检查、逐命题验证记录、证明—代码独立规则)和一道 Gate 4R(修订后重新过门),为各 Gate 增加 12 条客观 FAIL 触发条件与 5 类不可降级发现,要求 Stage 8 对每条 CORE 声明做一次可执行反例搜索,在三个人类检查点显示逐命题证据,并补上 `settings.json` 中已注册却缺失的产物保护 hook。详见 [CHANGELOG](./CHANGELOG.md)。
- ---
- ## 致谢与来源
- 本项目受 **pAI/MSc** 启发,并基于其 research pipeline 思想改造为理论经济学方向的 Claude Code Skill。
- Original pAI/MSc:
- - Mahmoud Abdelmoneum
- - Pierfrancesco Beneventano
- - Tomaso Poggio
- - MIT + Perseus Labs
- Reference:
- - [pAI/MSc: ML Theory Research with Humans on the Loop](https://arxiv.org/abs/2604.20622)
- - [PoggioAI_MSc GitHub Repository](https://github.com/PoggioAI/PoggioAI_MSc-claude)
- **反馈与优化: Gin,Luo Zijun**
- **模型库贡献: [hayeszhou](https://github.com/hayeszhou)**(空间动态一般均衡与贸易-劳动力动态模型条目,PR #3)
- ---
- ## 项目简介
- **pAI-Econ-claude** 是一个面向实证经济学家的 **human-in-the-loop Claude Code Skill**,旨在帮助研究者从经验现象、机制直觉和实证发现出发,补齐研究中的理论版图。
- 它并不试图替代理论经济学家的原创工作,也不声称能够自动发现新的理论前沿。相反,它的定位是作为理论与实证之间的桥梁:帮助实证研究者识别合适的经典模型家族,澄清核心经济机制,明确模型扩展相对于既有理论的新增部分,并将经验问题转化为更规范的理论表述。
- 很多实证研究并不缺少数据、识别策略或估计结果,真正薄弱的地方往往是理论机制不够清楚:为什么这个现象应该成立?它对应哪个经典模型?新增变量改变了什么?命题是否只是由假设直接推出?福利含义是否超过了估计结果本身?
- pAI-Econ-claude 试图为这些问题提供一个结构化工作流。它通过典范模型匹配、理论谱系检查、模型原语生成、假设审计、候选命题、证明草图和反例检查,帮助研究者把一个 empirical puzzle 转化为可讨论、可审查、可进一步合作发展的理论框架。
- 换句话说,它不是 AI 理论经济学家,而是一个面向实证研究者的理论建模脚手架:
- > 帮助你知道自己的经验发现可以放进哪个理论传统里、还缺少哪一块机制、应该向理论合作者提出什么样的问题。
- ---
- ## 它解决什么问题?
- 经济学研究里的理论分析部分常常不是卡在"不会写",而是卡在更早的阶段:
- - 研究问题是否真的清楚?
- - 这个想法应该放在哪个经典模型传统里?
- - 新机制相对于经典模型到底新增了什么?
- - 假设是否过强,是否只是为了推出想要的结论?
- - 命题是否非平凡,还是由假设直接推出?
- - 证明草图有哪些缺口?
- - 是否存在简单反例?
- - 经济学解释是否超过了形式结果本身?
- **pAI-Econ-claude 的定位是帮助研究者把理论建模过程显性化、文档化、可回溯化,并在关键节点保留人类判断。**
- ---
- ## 目标用户与使用责任
- ### 目标用户
- 本 Skill 的设计目标用户是**具备经济学理论基础的初级研究者**,包括:
- - 经济学、管理学等相关方向的研究生(硕士、博士)
- - 以实证研究为主、希望补齐理论机制的助理教授或博士后
- - 熟悉微观经济学基础(效用最大化、均衡概念、信息结构)的研究者
- 使用本 Skill 要求用户具备以下基本能力:
- - 能够独立判断一个均衡概念(如 BNE、SPE、竞争均衡)是否适合当前研究设定
- - 能够识别一个命题是否非平凡,或仅由假设直接推出
- - 能够评估一个理论机制是否与实证识别策略存在有意义的对应关系
- **本 Skill 不面向对经济学理论建模完全陌生的研究者。** 如果用户无法独立判断 AI 生成的模型结构和命题的质量,则无法对输出结果承担应有的学术责任。
- ### 使用责任
- > **使用者对最终发表成果负完全责任。**
- 本 Skill 是一个辅助工具,其输出(包括模型原语、命题、证明草图、论文框架和参考文献)均须经过使用者独立审核,方可用于任何学术写作和发表目的。
- 具体而言:
- - **Proof sketch 不是正式证明**:标注为 `GAP` 或 `FALSE_RISK` 的步骤须由研究者自行推导和验证,不得在未经核实的情况下写入论文
- - **文献引用须独立核查**:虽然 Stage 2 和 PDF 生成前均设有联网验证节点,但研究者仍须对最终发表的引用列表的准确性负责
- - **理论贡献须研究者判断**:AI 无法最终裁定一个命题是否具有足够的创新性以满足期刊要求,这一判断须由研究者和合作者在充分理解领域文献的基础上做出
- - **模型选择须研究者评估**:Canonical Model Matching 的建议仅供参考,研究者须根据自身对相关文献传统的理解做出最终选择
- 本项目及其作者不对使用本 Skill 生成的任何内容在学术发表中的准确性、原创性或充分性承担责任。
- ---
- ## 快速开始
- ### 安装
- ```bash
- git clone https://github.com/maxwell2732/pAI-Econ-claude.git
- cd pAI-Econ-claude
- ```
- 在该目录下打开 Claude Code,slash command 即自动可用:
- ```text
- /theoretical-economics-claude-skill "你的理论经济学研究想法"
- ```
- ---
- ## 运行模式
- pAI-Econ-claude 提供两种理论构建模式,共用同一套典范模型匹配、假设审计、证明完整性检查和人类在环机制。
- ### 1. Theory Development(默认)
- 开放式理论开发:拓展参数空间、寻找特殊情形、分析结论反转、增加机制、主动搜索反例,追求较广泛的理论贡献。适合独立理论研究。
- 不指定模式时运行的就是这个模式,行为与 v1.3.0 完全一致。
- ### 2. Empirical Companion
- > **From empirical results to the smallest theory that can explain them.**
- 面向实证论文的受约束理论构建模式:锁定研究者已经提出的 empirical story,用最少的 primitives 将其形式化,推出与实证设计一一对应的 hypotheses。
- 核心原则:
- > **Constrain scope, not rigor.**
- 这个模式缩小理论搜索空间。它不降低证明标准,也不会为了配合回归系数制造结论。
- | 维度 | Theory Development | Empirical Companion |
- |---|---|---|
- | 研究问题 | 可以拓宽、重构、一般化 | 锁定研究者的实证问题 |
- | 模型规模 | 理论需要多少就多少 | 能推出目标 hypotheses 的最小连贯模型 |
- | 命题 | 六种必需类型(E/U/C/W/M/B) | 每个 target hypothesis 一条,其余延后 |
- | 反例搜索 | 全参数空间广泛搜索 | 优先检查声明的实证域,域外结果记入 scope notes |
- | 数值模拟 | 按自身价值提供 | 仅在三个特定触发条件下建议 |
- | 新颖性要求 | 模型本身应构成理论贡献 | 模型可以只是实证分析的组织框架 |
- | 额外发现 | 进入主线 | 记入 `scope_notes.md` |
- 保持不变的部分:典范模型匹配(Stage 3b、Gate 2b/2c)、假设审计(Stage 5)、证明完整性(Gate 4)、反例检验(Stage 8)、数学审查(Gate 6)、引用核验规则,以及全部人类在环停点。
- ### 调用方式
- ```text
- /mode empirical-companion
- 我的实证论文发现:
- Baseline:
- 政策 X 显著提高 Y。
- Mechanism:
- X 通过降低融资约束 M 影响 Y。
- Heterogeneity:
- 效果主要集中在初始融资约束较高的企业。
- 请构建一个最小理论模型,为 baseline、mechanism 和 heterogeneity results
- 分别推出对应 hypotheses。
- ```
- 等价写法:
- ```text
- /mode empirical-companion --task path/to/empirical-brief.txt
- /theoretical-economics-claude-skill "
- mode: empirical-companion
- ...
- "
- ```
- ### Empirical Companion 工作流
- ```text
- Empirical scope lock
- ↓
- Canonical matching
- ↓
- Minimal model
- ↓
- Empirical–theory mapping
- ↓
- Propositions
- ↓
- Proof / consistency check
- ↓
- Empirical Alignment Gate
- ↓
- Theory section
- ```
- Stage 0-EC 会解析以下字段并写入 `outputs/empirical_scope.md`(scope contract):
- ```text
- Empirical question:
- Baseline result:
- Proposed mechanism:
- Mechanism test:
- Heterogeneity results:
- Key hypotheses to rationalize:
- Preferred theoretical tradition, if any:
- Scope exclusions:
- ```
- 前三项中的 empirical question、baseline result 和 key hypotheses 为必填。缺失字段最多追问三个问题,且合并在一条消息中。
- ### 该模式独有的产出
- | 文件 | 生成阶段 | 内容 |
- |---|---|---|
- | `outputs/empirical_scope.md` | Stage 0-EC | scope contract,后续所有阶段在其范围内工作 |
- | `outputs/minimality_check.md` | Stage 4/6 | 每个模型元素对应的实证功能;无实证角色的元素直接删除 |
- | `outputs/empirical_theory_map.md` | Stage 4/6 | empirical result → mechanism → primitive → proposition → hypothesis |
- | `outputs/scope_notes.md` | Stage 4–8 | 域外反转、边界情形、替代机制、可能扩展、额外命题 |
- | `gates/gate-ec-empirical-alignment.md` | Stage 6 之后 | Gate EC 判定 |
- `scope_notes.md` 中的内容仍然被检查和记录,默认不进入主线命题、hypotheses 和正文。仅在三种情况下可以进入正文:推翻某个 target hypothesis、对识别有关键影响、研究者明确要求。
- ### Gate EC — Empirical–Theory Alignment
- 在 Stage 6 和 Gate 3 之后、HiL-5 之前运行,共六项检查:
- | 检查 | 内容 |
- |---|---|
- | EC1 | 每个主要 proposition 是否对应至少一个 empirical result |
- | EC2 | 每个 target hypothesis 是否能从模型推出 |
- | EC3 | 是否存在未服务于实证分析的额外机制 |
- | EC4 | 模型是否引入超出实证论文所需的假设 |
- | EC5 | heterogeneity proposition 是否对应实证的 interaction/subgroup 分析 |
- | EC6 | mechanism proposition 与 mechanism test 测量的是否是同一个经济对象 |
- 判定沿用 pipeline 标准词汇 PASS / CONDITIONAL PASS / FAIL。EC6 是唯一不可降级的检查:如果论文声称某个实证结果检验机制 M,而模型中的 M 是另一个 latent object,该门必须 FAIL。
- ### 严谨性约束
- **目标 hypothesis 只是待推导的靶子。** 如果研究者期望 `X 提高 Y`,而模型只能推出 `符号取决于参数取值`,系统会如实报告,并给出最小充分条件:
- ```text
- TARGET HYPOTHESIS NOT DERIVED — H2
- What the model actually yields: sign depends on theta
- Minimal sufficient condition: theta > theta*
- Economic meaning: ...
- Support: EMPIRICAL / THEORETICAL / NONE FOUND
- ACCEPT CONDITIONAL ADD ASSUMPTION REVISE EMPIRICS
- ```
- 由研究者决定采纳哪一条。系统不会自行采纳该条件继续推进。
- **No assumption laundering.** 系统不能通过悄悄增加单调性、凸性、single-crossing、参数范围、函数形式或分布假设来制造与回归方向一致的结果。scope lock 之后引入的任何假设都会在 `assumption_audit.md` 中标记为 `ADDED-FOR-TARGET`,必须给出独立于目标结论的经济学理由,并接受 Gate EC 检查。
- ### 论文输出
- Stage 10 产出适合实证论文的理论章节:
- ```text
- 3. Conceptual Framework
- 3.1 Economic Environment
- 3.2 Model
- 3.3 Predictions
- Hypothesis 1: Baseline effect
- Hypothesis 2: Mechanism
- Hypothesis 3: Heterogeneity
- ```
- 目标长度 3–5 页,证明放入附录,不生成边界情形专节,实证论文未提出福利主张时不生成福利分析。
- 完整说明见 `docs/mode-empirical-companion.md`;pipeline 实际执行的规范见 `prompts/mode-empirical-companion.md`。
- ---
- ## 使用场景
- pAI-Econ-claude 支持不同成熟度的理论想法。你不必每次都跑完整 pipeline,可以根据任务选择合适入口。
- 下面五个入口都在默认的 **Theory Development** 模式下运行。实证论文的理论章节请使用上一节的 **Empirical Companion** 模式。
- ### 1. Model Extension Mode:从经典模型出发做机制扩展
- 当你已经知道大致模型家族,希望加入一个新机制时,可以使用这个模式。
- 例如:
- ```text
- /theoretical-economics-claude-skill "
- mode: model_extension
- Extend a search model by adding product healthfulness and costly attention to nutrition labels.
- Can a front-of-package label increase the probability that consumers choose healthier food?
- "
- ```
- Skill 会帮助你回答:
- - 这个想法继承了哪个经典 search model?
- - 新增的 healthfulness 机制改变了什么?
- - 消费者什么时候会主动查看营养标签?
- - 降低信息成本是否一定提高健康食品购买概率?
- - 是否存在反例或边界情形?
- - 这个扩展是否有足够理论贡献?
- ---
- ### 2. Phenomenon-to-Model Mode:从经济现象匹配理论模型
- 当你有一个现象或机制直觉,但不确定该用什么理论模型时,可以使用这个模式。
- 例如:
- ```text
- /theoretical-economics-claude-skill "
- mode: phenomenon_to_model
- I want to incorporate genetic endowment into a health capital framework.
- Genetic endowment affects productivity through childhood environment, health investment,
- and human capital formation. Which theoretical model is most suitable?
- "
- ```
- Skill 会比较多个候选模型家族,例如:
- - Grossman health capital model
- - Becker / Ben-Porath human capital investment model
- - Cunha-Heckman skill formation framework
- - Roy model of comparative advantage
- - lifecycle investment model
- - intergenerational human capital model
- 然后推荐一个 baseline model,并解释其他模型为什么适合或不适合。
- ---
- ### 3. Model Critique Mode:审查已有理论模型
- 如果你已经有模型原语、假设或命题,可以让 Skill 像理论经济学 referee 一样进行审查。
- ```text
- /theoretical-economics-claude-skill "
- mode: model_critique
- Here is my model setup:
- [粘贴模型原语、时序、效用函数、均衡定义和命题]
- Please audit model coherence, assumptions, non-triviality, proof gaps, and possible counterexamples.
- "
- ```
- 它会重点检查:
- - 模型是否闭合?
- - 时序是否清楚?
- - 信息结构是否完整?
- - 均衡概念是否合适?
- - 假设是否只是为了推出想要的结论?
- - 命题是否非平凡?
- - 证明草图是否存在跳步?
- - 是否存在 2-agent、2-period、binary-action 的简单反例?
- ---
- ### 4. Full Pipeline Mode:从研究想法跑完整理论工作流
- 当你只有一个早期想法,希望从 intuition 一直推进到论文框架时,可以使用完整流程。
- ```text
- /theoretical-economics-claude-skill "
- mode: full_pipeline
- Investigate whether a principal facing a privately informed agent can achieve first-best efficiency
- through a forcing contract when the agent's outside option is type-dependent.
- "
- ```
- 完整输出包括:
- - refined research puzzle
- - literature positioning plan
- - canonical model match
- - model primitives
- - assumption audit
- - candidate propositions
- - proof sketches
- - counterexamples
- - economic interpretation
- - manuscript skeleton(含 LaTeX 源文件和学术格式 PDF,pdflatex 编译)
- ---
- ### 5. Manuscript Skeleton Only:只生成论文框架
- 当模型、命题和主要结论已经比较清楚,只需要整理成 working paper 结构时,可以使用这个模式。
- ```text
- /theoretical-economics-claude-skill "
- mode: manuscript_skeleton_only
- Here are my model, propositions, and proof sketches:
- [粘贴已有内容]
- Please organize them into a theoretical economics working paper skeleton.
- "
- ```
- ---
- ## 工作流
- pAI-Econ-claude 使用一个分阶段、可回溯的人机协作流程。
- **关于 Stage 2a — Empirical Reality Check(现实背景校验):**
- 在文献定位完成后、进入理论建模之前,pipeline 会先执行一次最小必要的现实背景校验(Stage 2a),并通过 **Gate 1b(Reality Fit Gate)** 进行把关。
- 这一步的目的是:在模型结构确定之前,检查用户描述的市场结构、制度情境或群体差异,是否与拟采用的理论模型家族的事实性假设相匹配。具体包括:
- - 市场集中度是否支持"单一主导企业 + 原子化 fringe"结构,还是实际上是寡头市场?
- - 是否有重要的战略竞争者被忽视?
- - 产品是否被错误地当成同质品?
- - 约束条件是否被错误识别(如分销渠道约束被写成生产产能约束)?
- - 城乡、地区或群体差异的声明是否有公开数据支持?
- Gate 1b 的三种结果:
- - **PASS**:事实性假设与现实证据匹配,直接进入 Stage 3。
- - **CONDITIONAL PASS (REFRAME)**:部分假设无法验证,但模型仍可继续,前提是论文明确将研究情境描述为"风格化假想市场",而非声称描述具体现实市场。
- - **FAIL (REROUTE)**:核心假设与现实数据矛盾,须先回到 Stage 1 修正研究问题,或重新在 Stage 3b 选择更合适的典范模型家族。
- **关于 Stage 7b — Numerical Simulation(数值模拟与计算示例,可选模块):**
- > Numerical simulation is optional and runs only after explicit user approval. When selected, the workflow produces reproducible code, machine-readable results, and figures in both PNG and PDF formats. Numerical evidence is used for verification, counterexample search, and illustration, not as a substitute for formal proof.
- >
- > 数值模拟是完全可选的,只有在用户明确批准后才会运行。一旦选择运行,工作流会产出可复现代码、机器可读结果,以及 PNG 和 PDF 双格式图形。数值证据用于公式核验、反例搜索和机制示例,**不能替代形式化证明**。
- Stage 7(Proof Sketch)完成后,pipeline 一定会在 **HiL-N1** 停下来询问用户是否进行数值模拟。完整分支逻辑:
- ```text
- Stage 7 — Proof Sketch (+ Gate 4)
- → 询问用户是否进行数值模拟(HiL-N1)
- NO → 不创建任何数值产物,直接进入 Stage 8
- PLAN ONLY → 只生成 numerical_simulation_plan.md,不执行任何代码,暂停等待
- CUSTOM → 先收集用户的模拟需求(命题、变量、基准参数、参数范围、
- 坐标轴、模拟类型、图形格式)→ 生成计划
- YES → 生成计划
- → 用户批准计划(HiL-N2 —— 未选择 APPROVE PLAN 前禁止执行任何代码)
- → 生成代码 → 运行模拟 → 保存机器可读 CSV 结果
- → 生成 PNG 和 PDF 图形
- → Gate 4b — Numerical Integrity Gate(数值完整性门)
- → 人工审阅数值结果(HiL-N3)
- → Stage 8 — Counterexample Finder(带数值交接信息)
- ```
- 每个参数都必须分类(理论归一化 / 有实证依据 / 示例性 / 用户指定);每个数值结果都必须带认识论标签(如 `NUMERICALLY VERIFIED FOR SPECIFIED PARAMETERS`、`COUNTEREXAMPLE FOUND`、`NOT A PROOF`);图形只有在用户于 HiL-N3 明确选择 `USE FIGURES IN MANUSCRIPT` 后才能进入论文(授权后默认在正文加入 1–2 张示例图:核心机制/福利图 + 至多一张参数扫描/regime 图,其余图形保留在工作区或附录)。如果数值模拟发现核心命题的反例,原始未修改命题将被禁止进入 Stage 10,直到在 Stage 8 / HiL-6 得到解决。
- **关于两种运行模式(v1.4.0 新增):**
- pipeline 支持两种理论构建模式,共用同一套典范模型匹配、假设审计和证明完整性检查。默认的 **Theory Development** 模式行为与既往版本一致。**Empirical Companion** 模式面向实证论文:Stage 0 之后先执行 Stage 0-EC 锁定实证范围,Stage 4 启用 Minimal Model Principle,Stage 6 之后加入 Gate EC 检查实证与理论的对应关系,HiL-5 改为 EMPIRICAL COMPANION CHECKPOINT。上图中的 Stage 0-EC 与 Gate EC 仅在该模式下运行。详见上文的 [运行模式](#运行模式) 一节。
- **关于 Gate 6 — Mathematical Review(数学审查门,v1.3.0 新增):**
- `manuscript.tex` 写完之后、编译 PDF 之前,pipeline 会强制运行一次全文数学审查。这个门的动机来自实际观察到的失误模式:均衡方程、一阶条件被包进 `proposition` 环境,当成研究结果呈现。五项检查:
- - **陈述分类** — 每个定理类环境(definition / assumption / lemma / proposition / corollary / remark)的标签必须与内容匹配;均衡条件、FOC、恒等式属于模型设定部分,绝不允许标成 Proposition
- - **独立重推导** — 每条展示推导(FOC、闭式解、比较静态符号)都先从模型原语独立推一遍,再与稿件逐项对照,避免审查者顺着稿件的错误代数往下读
- - **符号一致性** — 符号先定义后使用,一个符号不得指代两个对象
- - **命题与证明匹配** — 证明的结论必须恰好是命题的断言,量词必须对得上("对所有参数成立"的断言只在基准点验证过即判不合格)
- - **定义域与边界** — 除零、对非正数取对数、缺失内点条件等
- 低级错误(误标、不改变任何结论方向的代数笔误)直接改正并回写到上游文件(`candidate_propositions.md`、`proof_sketches.md` 等),全部记录在 `gates/gate-06-math-review.md` 的错误表中;实质性错误(重推导得出相反符号、证明未证得所声称的命题)会暂停 pipeline,按标准 gate 失败协议交研究者决定。审查未通过前禁止编译 PDF。
- 上游同时增加了两道对应检查:Gate 3 新增陈述分类检查(Check E,在命题生成源头拦截误标),Gate 4 新增证明草图关键代数的独立重推导检查(Check 7)。
- **关于声明验证 — Entailment Ledger、验证记录与 Gate 4R(v1.5.0 新增):**
- Gate 4 的 Check 7 与 Gate 6 的 Check M2 都从模型原语独立重推导展示公式,两者都做得称职。从一条已验证的公式,到写在它上面那句带量词的断言,这一步此前没有任何检查。一次实际运行中,外部评审找到的四处数学缺陷,代数全部正确。
- v1.5.0 把"验证推导"和"验证声明"拆成两件事,并补上后者:
- - **Entailment Ledger**(`prompts/entailment-ledger.md`)— 每条声明跑九条链:L1 必要性、L2 充分性、L3 严格性、L4 符号算术、L5 因子正性、L6 局部到整体、L7 量词顺序、L8 角点覆盖、L9 定义同一性。外加九项支撑与分布清单(密度正性、支撑连通性、门槛内点性、乘积支撑、有限矩、正方差、条件集测度、原子、政策不变性)、十二行按模型家族划分的正则性条件,以及在边界、极限或完备点处取值的声明的可满足性程序。L3、L4、L5 与可满足性都是机械检查,每条声明几分钟,上述四处缺陷全部在这一层被抓住。
- - **逐命题验证记录**(`verification_record.json`)— 五种状态:`VERIFIED`、`CONDITIONALLY VALID`、`INVALID`、`NOT VERIFIED`、`NUMERICALLY SUPPORTED`,每种状态写明最低证据要求。声明创建时一律 `NOT VERIFIED`,只有 gate 能提升状态;声明文本一经改动,`claim_text_sha256` 对不上,状态即重置。同一文件内还有 obligation ledger,记录每条未结事项的解除条件与是否阻塞稿件。
- - **证明—代码独立**(`prompts/proof-code-independence.md`)— 验证代码不得继承作者实现的分类器和可行域边界;I0–I4 证据分级;每个模型变体各自推导最优性系统与每个约束的绑定条件;网格可用率(usability ratio)与 regime 测试矩阵。
- - **Gate 4R(Revision Re-gate)** — 位于 HiL-6 之后、Stage 9 之前,只对文本改过的声明运行 Gate 4 的 Check 1/3/7/8,外加一项检查:把原反例实例代入新假设,确认新假设确实排除了它。没有声明改动时记 `NOT RUN`,不产生成本。此前在 Stage 8 或 HiL-6 改写的声明,第一个读到新措辞的审查者是 Gate 6,也就是流水线的最后一道门。
- Stage 8 另外要求对每条 CORE 声明做一次**可执行**反例搜索:数值脚本(实例化模型、逐条检验假设、算出结论)或写出来的符号构造,搜索方向由 Ledger 的 flag 机械映射得到。散文式的"想过了,应该没有反例"不再算完成;`SEARCH NOT PERFORMED` 是允许且必须记录的结果,它把该声明的上限封在 `CONDITIONALLY VALID`。
- HiL-5、HiL-N3、HiL-6 三个检查点都显示逐命题状态表、独立性等级、entailment 摘要与未结事项数,附一行必填的 `Checks not performed`,并提供 `SHOW EVIDENCE [P_n]` 查看单条声明的记录与推导。
- ```mermaid
- flowchart TD
- A["0. Intake<br/>研究想法摄入"] --> A2["0-EC. Empirical Scope Lock<br/>实证范围锁定<br/>(仅 empirical-companion 模式)"]
- A2 --> B["1. Puzzle Refinement<br/>研究问题精炼"]
- B --> C["2. Literature Positioning<br/>文献定位与检索计划"]
- C --> C2["2a. Empirical Reality Check<br/>现实背景校验(Gate 1b)"]
- C2 --> D["3. Persona Council<br/>理论评审委员会"]
- D --> E["3b. Canonical Model Matching<br/>典范模型匹配"]
- E --> F["4. Model Primitives<br/>模型原语"]
- F --> G["5. Assumption Audit<br/>假设审计"]
- G --> H["6. Proposition Generator<br/>候选命题"]
- H --> HE{"Gate EC<br/>实证—理论对齐<br/>(仅 empirical-companion 模式)"}
- HE --> I["7. Proof Sketch<br/>证明草图"]
- I --> N1{"HiL-N1<br/>是否数值模拟?"}
- N1 -- "NO(默认路径)" --> J["8. Counterexample Finder<br/>反例与边界检查"]
- N1 -- "YES / CUSTOM" --> N2["7b. Numerical Simulation<br/>计划 → 用户批准 → 代码<br/>CSV + PNG/PDF 图形<br/>(Gate 4b)"]
- N1 -- "PLAN ONLY" --> NP["仅生成计划并暂停<br/>(不执行代码)"]
- N2 --> J
- J --> JR{"Gate 4R<br/>仅对改过文本的声明重新过门<br/>(无改动则 NOT RUN)"}
- JR --> K["9. Economic Interpretation<br/>经济学解释"]
- K --> L["10. Manuscript Skeleton<br/>论文框架 → Gate 6 数学审查 → PDF"]
- ```
- ---
- ## 核心阶段
- | 阶段 | 名称 | 主要产出 |
- |---|---|---|
- | 0 | Intake | `research_intake.md` |
- | **0-EC** | **Empirical Scope Lock**(仅 empirical-companion 模式) | `empirical_scope.md` |
- | 1 | Puzzle Refinement | `research_puzzle.md` |
- | 2 | Literature Positioning | `literature_positioning.md` |
- | 2a | Empirical Reality Check | `empirical_reality_check.md` |
- | 3 | Theory Persona Council | `persona_council.md` |
- | 3b | Canonical Model Matching | `canonical_model_match.md` |
- | 4 | Model Primitives | `model_primitives.md`(+ empirical-companion 模式下的 `minimality_check.md`、`empirical_theory_map.md`) |
- | 5 | Assumption Audit | `assumption_audit.md` |
- | 6 | Proposition Generator | `candidate_propositions.md`(+ empirical-companion 模式下的 `scope_notes.md`、完成后的 `empirical_theory_map.md`) |
- | 7 | Proof Sketch | `proof_sketches.md` |
- | **7b** | **Numerical Simulation(可选,须用户明确选择)** | `numerical_simulation_report.md` + `numerical_code/` + `numerical_results/` + `numerical_figures/`(PNG + PDF) |
- | 8 | Counterexample Finder | `counterexamples_and_edge_cases.md` |
- | 9 | Economic Interpretation | `economic_interpretation.md` |
- | 10 | Manuscript Skeleton | `manuscript_skeleton.md` + `manuscript_skeleton.tex` + `manuscript_skeleton.pdf` |
- 工作区还有两个状态文件:`state.json` 记流水线位置与研究者决定;`verification_record.json` 记逐命题的验证状态与证据,由 Stage 6 创建,Stage 7/7b/8 填字段,Gate 3/4/4b/4R/6 写状态。`state.json → active_propositions` 仍是声明 ID 列表,索引到后者,所以 v1.5.0 之前创建的工作区 `--resume` 照旧可用(没有该文件时,所有声明按 `NOT VERIFIED` 读取)。
- Gate 4R 位于 HiL-6 与 Stage 9 之间,只对改过文本的声明运行,没有改动时记 `NOT RUN — no revised claims`,不产生成本。
- ---
- ## 理论模型库
- pAI-Econ-claude 内置一个 `model_library/`,用于在建模前先匹配经典理论模型家族。
- 这一步非常重要,因为理论经济学研究不应该从零开始"凭空造模型",而应先回答:
- > 当前研究想法最接近哪个经典模型?
- > 它继承了什么?改变了什么?新增机制在哪里?
- ### 通用理论模型库
- | 模型家族 | 适用问题 |
- |---|---|
- | Consumer Choice | 消费者选择、效用最大化 |
- | Indirect Utility / Expenditure Minimization | 消费者理论中的对偶问题 |
- | Discrete Choice / Random Utility | 离散选择、异质偏好 |
- | Search Models | 搜索成本、停止规则、信息获取 |
- | Costly Information Acquisition | 注意力成本、认知成本、信息处理 |
- | Rational Inattention | 有限注意力、信息容量约束 |
- | Signaling | 信号传递、教育信号、质量信号 |
- | Screening | 逆向选择下的机制设计 |
- | Moral Hazard | 隐藏行动、激励合同 |
- | Adverse Selection | 柠檬市场、质量不可观测 |
- | Hotelling / Product Differentiation | 产品差异化、空间竞争 |
- | Disclosure / Persuasion | 信息披露、贝叶斯劝说 |
- | Mechanism Design | 显示原理、激励相容 |
- | Matching Models | 双边匹配、分配市场 |
- | Matching with Cutoffs | 录取分数线、门槛出清、配额分配 |
- | Social Learning | 羊群行为、信息瀑布 |
- | Dynamic Optimization | Bellman 方程、生命周期选择 |
- | OLG / Life-Cycle Models | 代际模型、生命周期投资 |
- | Principal-Agent | 委托代理、合同设计 |
- | General Equilibrium | 竞争均衡、市场出清 |
- | Political Economy | 投票、集体选择、制度设计 |
- ---
- ### 产业组织专题库
- | 模型家族 | 适用问题 |
- |---|---|
- | Oligopoly Competition | Cournot 数量竞争、Bertrand 价格竞争、Stackelberg 先动优势 |
- | Entry Deterrence | 限制性定价、产能承诺、进入阻止与进入容纳 |
- | Two-Sided Markets / Platforms | 双边市场定价、网络效应、平台竞争 |
- | Price Discrimination | 一二三度价格歧视、版本化、市场细分 |
- ---
- ### 国际贸易专题库
- | 模型家族 | 适用问题 |
- |---|---|
- | Comparative Advantage / Ricardian | 比较优势、贸易专业化分工、技术差异驱动贸易 |
- | Heckscher-Ohlin | 要素禀赋与贸易模式、Stolper-Samuelson、Rybczynski、要素价格均等化 |
- | New Trade Theory / Krugman (1980) | 产业内贸易、规模经济、品种效应、本土市场效应 |
- | Melitz (2003) — Firm Heterogeneity | 企业异质性、出口门槛、选择效应、贸易的生产率重配置收益 |
- ---
- ### 人力资本与劳动经济学专题库
- 针对人力资本、教育、劳动市场、自动化和 AI 影响,Skill 还内置了专题模型库(均为具备均衡概念和可证命题的结构理论模型)。
- | 模型家族 | 适用问题 |
- |---|---|
- | Becker Human Capital | 一般与专用人力资本投资 |
- | Ben-Porath Model | 生命周期人力资本积累 |
- | Roy Model | 部门选择、职业选择、比较优势 |
- | Cunha-Heckman Skill Formation | 技能形成、早期投资、动态互补 |
- | Technology of Skill Formation | 技能生产函数(CES) |
- | Self-Productivity & Dynamic Complementarity | 技能形成的自我生产性与动态互补性 |
- | Early Childhood Investment | 早期儿童发展投资与最优政策 |
- | Intergenerational Transmission | 人力资本代际传递 |
- | Education under Credit Constraints | 信贷约束下的教育选择 |
- | Occupational Choice & Comparative Advantage | 职业选择与比较优势 |
- | Compensating Differentials | 职业风险与非货币属性的补偿性差别;工资管制下的转嫁 |
- | Cobweb Supply Lags | 长训练周期职业的进入动态、预期与周期 |
- | Acemoglu-Restrepo Task-Based Framework | 任务型生产、自动化与新任务 |
- | Automation Displacement / Reinstatement | 替代效应、恢复效应、新任务创造 |
- | Human Capital Adaptation to AI | AI 冲击下的人力资本调整 |
- | Directed Technical Change / SBTC | 定向技术进步与技能偏向技术变迁 |
- ---
- ## 质量控制 Gates
- Skill 内置多个质量门,用来避免"看起来像理论,其实没有理论贡献"的问题。
- | Gate | 名称 | 检查内容 | 失败后建议 |
- |---|---|---|---|
- | Gate 1 | Novelty Risk | 问题是否可能已被文献回答 | 回到研究问题精炼 |
- | Gate 2b | Canonical Fit | 模型家族是否匹配,是否只是经典模型换名 | 回到典范模型匹配 |
- | Gate 2c | Theory Lineage | 是否明确理论祖先、继承内容和新增机制 | 回到典范模型匹配 |
- | Gate 2 | Model Coherence | 模型原语、时序、信息结构是否一致 | 回到模型原语 |
- | Gate 3 | Non-triviality | 命题是否非平凡,是否只是从假设直接推出 | 回到假设或命题 |
- | Gate 4 | Proof Integrity | 证明草图是否诚实标注缺口;关键代数(FOC、闭式解、比较静态符号)是否通过独立重推导验算;Check 8 蕴含检查:九条链、支撑与分布清单、假设集可满足性 | 回到命题或证明 |
- | Gate 4b | Numerical Integrity(可选;仅当 Stage 7b 运行后) | 公式—代码一致性、可复现性、参数透明度、数值稳健性、结果完整性、认识论标签 | 回到 Stage 7b(修代码/参数)或 Stage 6(修改命题) |
- | Gate 4R | Revision Re-gate(HiL-6 之后、Stage 9 之前;只查改过文本的声明) | 修订是否被登记为修订(新 ID、状态重置)、新陈述的假设用量与蕴含检查、改动过的代数重推导、原反例是否被新假设真正排除、CORE 声明是否仍有针对新文本的反例搜索 | 回到 Stage 8(修订本身不对)或 Stage 6(声明需重述) |
- | Gate 5 | Economic Meaning | 经济解释是否超过形式结果 | 回到经济学解释 |
- | Gate 6 | Mathematical Review(manuscript.tex 写完后、编译 PDF 前) | 陈述分类是否正确(均衡条件、FOC 不得标成 Proposition)、逐条独立重推导、符号一致性、证明与命题是否匹配、定义域与边界情形;Check M6 以稿件印出的措辞重跑蕴含检查 | 低级错误直接改正并回写到上游文件;实质性错误回到命题(Stage 6)或证明(Stage 7) |
- | Gate EC | Empirical–Theory Alignment(仅 empirical-companion 模式;Stage 6 与 Gate 3 之后) | 命题是否都对应实证结果、target hypotheses 是否都能推出、是否存在多余机制、假设是否超出实证论文所需、heterogeneity 命题是否对应实证 interaction、mechanism 命题与 mechanism test 是否测量同一对象 | 回到命题(EC1/EC2/EC5)、模型原语(EC3/EC4)或典范模型匹配(EC6) |
- Gate 失败不会被自动隐藏,也不会被包装成通过。Skill 会明确输出:
- - failure reason
- - severity
- - recommended loopback stage
- - whether a human override is possible
- ### 客观 FAIL 触发条件(v1.5.0)
- 各 gate 原有的"WARNING 条数 → 判定"算术由同一个 agent 提出发现、又由它数条数,v1.5.0 在其上加了十二条与条数无关的客观触发条件。**任一条触发期间,不得给出高于 FAIL 的判定。**
- | ID | 触发条件 | 适用 gate |
- |---|---|---|
- | FT-1 | 某条声明的 Entailment Ledger 有任一链返回 `FAIL` | 3, 4, 4R, 6 |
- | FT-2 | 声明与本门自己验算出的表达式相矛盾 | 4, 4R, 6 |
- | FT-3 | 存在满足声明全部前提的有效反例 | 4, 4b, 4R, 6 |
- | FT-4 | 在用声明的假设集 `INFEASIBLE_AT_STATED_POINT` | 3, 4, 4R, 6 |
- | FT-5 | CORE 声明的 `undeclared_but_used` 非空(假设洗白) | 4, 4R |
- | FT-6 | 结论依赖的支撑清单项为 `MISSING` | 3, 4, 4R, 6 |
- | FT-7 | 验证者与作者实现在任一网格点上的约束绑定状态不一致 | 4b |
- | FT-8 | `usability_ratio < 0.5`,或存在无法由模型推出的网格排除规则 | 4b |
- | FT-9 | 用 I3 或 I4 级独立性充当 `VERIFIED` 的证据 | 4, 4b, 4R, 6 |
- | FT-10 | `VERIFIED` 或 `CONDITIONALLY VALID` 的声明依赖一条 `CONJECTURE` | 4, 4R, 6 |
- | FT-11 | 证明只立住了比陈述更弱的结论,严格性亦算在内 | 6 |
- | FT-12 | 文本已改(`claim_text_sha256` 变化)却仍挂着高于 `NOT VERIFIED` 的状态 | 4, 4R, 6 |
- ### 五类不可降级发现
- 数学矛盾(ND-1)、有效反例(ND-2)、约束分类错误(ND-3)、缺失承重证明(ND-4)、假设集不可满足(ND-5)。研究者仍然掌握最终处置权,被取消的是"发现自行消失"这个选项:对不可降级发现,`PROCEED WITH CAVEAT` 只在把该发现写进稿件对应结果处的那个版本中可用。
- ### 降级记录与未结事项
- 某个 gate 命中了 FAIL 触发条件却判断不应 FAIL 时,必须按名记入 `fail_conditions_hit`(无论后续是否降级)、写明降级理由,并等研究者 `APPROVE DOWNGRADE` 或 `REVERSE DOWNGRADE`;未获批准的降级禁止该声明进入稿件。每条 WARNING、每个 ledger `GAP`、每项 CONDITIONAL PASS 附带条件都写入 obligation ledger;**每个 gate 在跑自己的检查之前,先读完所有未结事项,逐条记 `DISCHARGED`(附证据路径)或 `STILL OPEN`。** 补救措施做过了并不等于事项已结,解除需要的是"该补救确实堵住了当初那个洞"的证据。
- ---
- ## 人类在环检查点
- 理论经济学中的关键判断不应由 agent 自动决定。因此 Skill 设置了多个必须由研究者确认的节点。
- | 检查点 | 位置 | 研究者需要决定 |
- |---|---|---|
- | HiL-1 | Puzzle Refinement 后 | 是否接受研究问题 |
- | HiL-2 | Literature Positioning 后 | 是否接受文献定位 |
- | HiL-3 | Persona Council 后 | 是否接受理论评审结论 |
- | HiL-4 | Model Primitives 后 | 确认均衡概念;这是硬停点 |
- | HiL-5 | Proposition Generator 后 | 选择哪些命题进入后续分析;在 empirical-companion 模式下改为 EMPIRICAL COMPANION CHECKPOINT,展示 empirical result → model mechanism → proposition → hypothesis 的对应关系,选项为 APPROVE / EDIT / RETURN TO MODEL。附逐命题验证状态表与 `SHOW EVIDENCE [P_n]` |
- | HiL-N1 | Proof Sketch 后 | 是否进行数值模拟(YES / NO / PLAN ONLY / CUSTOM)——Stage 7b 绝不默认运行 |
- | HiL-N2 | 数值模拟计划生成后 | 批准模拟计划与参数设计——未批准前禁止执行任何代码 |
- | HiL-N3 | 模拟执行 + Gate 4b 后 | 接受/修改数值结果;决定图形是否允许进入论文。附每条结果的认识论标签、独立性等级、网格可用率与已测 regime 数 |
- | HiL-6 | Counterexample Finder 后 | 如何处理反例与边界情形。附每条声明的反例搜索结果(FOUND / NONE FOUND / NOT PERFORMED),并在选择前说明:每一种处置都会生成一条新声明,随后由 Gate 4R 复查 |
- 其中 **HiL-4 是 hard stop**。均衡概念,例如 Nash、SPE、BNE、PBE、competitive equilibrium 等,必须由研究者确认后才能进入下一阶段。
- 自 v1.5.0 起,凡报告 gate 判定的检查点(HiL-5、HiL-N3、HiL-6)都附一个由 `verification_record.json` 生成的证据块。三条规则让它可读:空列按空列打印(`—` 表示该字段为 null,这本身是信息);`Checks not performed` 是必填行,不是可省略项;`SHOW EVIDENCE [P_n]` 只读、可重复,让研究者查一条声明而不必翻遍 gate 文件。
- 此外还有两处硬停:任一声明落到 `INVALID`,在发现它的那个 stage 或 gate 立即停下;进入 Stage 10 时仍有 CORE 声明停在 `NOT VERIFIED`,在写 `manuscript.tex` 之前停下,给出五个处置选项(证明 / 弱化 / 降为 conjecture / 删除 / 在稿件中披露缺口)。
- ---
- ## 五个理论评审 Persona
- 在 Persona Council 阶段,Skill 会模拟五类理论经济学评审者进行两轮讨论。
- | Persona | 关注点 |
- |---|---|
- | Mechanism Theorist | 机制是否清楚、有趣、非平凡 |
- | Mathematical Referee | 模型是否可形式化,证明是否可能成立 |
- | Economic Intuition Referee | 结果是否有真正经济学含义 |
- | Journal Positioning Referee | 更像投向哪个理论或应用理论期刊 |
- | Brutal Skeptic | 最强反对意见是什么 |
- Brutal Skeptic 的职责是攻击项目。如果一个想法能经受住这个 persona 的质疑,才更值得继续推进。
- ---
- ## 输出结构
- 每次运行的产出统一存放在 `Exploration/` 目录下,按项目编号和模型简写命名。
- 自 2026 年 7 月 9 日起,`Exploration/` 整体列入 `.gitignore`:新项目工作区和生成的稿件默认只保留在本地,不会随仓库提交。如需公开某个项目,手动执行:
- ```bash
- git add -f Exploration/Project_NNN_<Name>/
- ```
- ```text
- Exploration/
- └── Project_NNN_<ModelAbbrev>/ ← 例:Project_001_HumanCapitalAutomation
- ├── state.json
- ├── verification_record.json ← 逐命题状态与证据(Stage 6 起)
- ├── verification/
- │ ├── derivations/ ← 每条重推导声明一个文件:写过程,不写结论词
- │ ├── numerical/ ← 最优性系统、独立重实现
- │ └── counterexamples/ ← 反例搜索脚本与找到的实例
- ├── initial_context/
- │ └── hypothesis.md
- ├── outputs/
- │ ├── research_intake.md
- │ ├── empirical_scope.md ← Stage 0-EC:仅 empirical-companion 模式
- │ ├── research_puzzle.md
- │ ├── literature_positioning.md
- │ ├── persona_council.md
- │ ├── canonical_model_match.md
- │ ├── model_primitives.md
- │ ├── minimality_check.md ← Stage 4/6:仅 empirical-companion 模式
- │ ├── empirical_theory_map.md ← Stage 4/6:仅 empirical-companion 模式
- │ ├── assumption_audit.md
- │ ├── candidate_propositions.md
- │ ├── scope_notes.md ← Stage 4–8:仅 empirical-companion 模式
- │ ├── proof_sketches.md
- │ ├── numerical_simulation_decision.md ← Stage 7b(可选):HiL-N1 决策记录
- │ ├── numerical_simulation_plan.md ← Stage 7b(可选):PLAN ONLY / CUSTOM / YES
- │ ├── parameter_definitions.md ← Stage 7b(可选):参数分类表
- │ ├── numerical_simulation_report.md ← Stage 7b(可选):批准执行后生成
- │ ├── numerical_code/ ← Stage 7b(可选):可复现 Python 脚本
- │ ├── numerical_results/ ← Stage 7b(可选):机器可读 CSV 结果
- │ ├── numerical_figures/ ← Stage 7b(可选):图形,PNG + PDF 双格式
- │ ├── counterexamples_and_edge_cases.md
- │ ├── economic_interpretation.md
- │ ├── manuscript_skeleton.md
- │ ├── manuscript_skeleton.tex ← LaTeX 源文件(pdflatex + Computer Modern)
- │ └── manuscript_skeleton.pdf ← 学术排版 PDF(pdflatex + Computer Modern)
- ├── gates/
- │ ├── gate-01-novelty-risk.md
- │ ├── gate-02b-canonical-fit.md
- │ ├── gate-02c-theory-lineage.md
- │ ├── gate-02-model-coherence.md
- │ ├── gate-03-non-triviality.md
- │ ├── gate-04-proof-integrity.md
- │ ├── gate-04b-numerical-integrity.md ← Stage 7b(可选):仅当模拟运行后
- │ ├── gate-04r-revision-regate.md ← HiL-6 之后:只查改过文本的声明
- │ ├── gate-05-economic-meaning.md
- │ ├── gate-06-math-review.md ← manuscript.tex 写完后、编译前
- │ └── gate-ec-empirical-alignment.md ← Stage 6 之后:仅 empirical-companion 模式
- └── logs/
- └── stage-log.md
- ```
- ---
- ## 设计原则
- ### 1. 人类在环,而不是全自动研究
- 理论经济学研究中的核心判断,例如研究问题是否有意义、均衡概念是否合适、命题是否值得推进、反例是否致命,必须由研究者决定。
- AI 可以辅助生成、审查和反驳,但不应替代研究者做不可逆判断。
- ---
- ### 2. 先匹配经典模型,再构造新模型
- Skill 在正式定义模型原语之前,会先经过 **Canonical Model Matching**。
- 这一步强制回答:
- - 最接近的经典模型是什么?
- - 当前模型继承了哪些结构?
- - 新增机制是什么?
- - 新结果是否不可由经典模型直接推出?
- 这可以减少"经典模型换皮"的风险。
- ---
- ### 3. 诚实标注不确定性
- Proof Sketch 阶段不会把草图包装成严格证明。每个证明步骤会被标注为:
- - `SOLID`
- - `PLAUSIBLE`
- - `GAP`
- - `FALSE_RISK`
- 这使研究者可以清楚看到哪些地方已经比较稳,哪些地方还只是 conjecture-level。
- ---
- ### 4. 主动寻找反例
- Stage 8 专门寻找反例和边界情形,包括:
- - 2-agent case
- - 2-period case
- - binary-action case
- - corner solution
- - alternative equilibrium
- - violation of key assumptions
- 这一步的目标是尽早发现模型可能失败在哪里。它不负责让模型更好看。
- 每条 CORE 声明另有一次**必做的可执行搜索**:数值脚本(在显式参数点实例化模型、逐条检验每个前提、算出结论)或写出来的符号构造,方向由 Entailment Ledger 的 flag 决定(L3 flag → 构造等号成立的配置;S2 `MISSING` → 在支撑中挖一个洞)。这条要求来自一次实际运行:九次散文式尝试对某条命题得出 ROBUST,而一个七行脚本就把它推翻了。`SEARCH NOT PERFORMED` 允许出现、必须记录,并把该声明封在 `CONDITIONALLY VALID` 以下。
- ---
- ## 项目结构
- ```text
- pAI-Econ-claude/
- ├── SKILL.md # 流水线编排:阶段路由、Gate 逻辑、HiL 协议
- ├── CLAUDE.md # 项目级规则(文献验证要求、PDF 格式标准等)
- ├── README.md # 中文说明(本文件)
- ├── README_EN.md # 英文说明
- ├── THEORETICAL_ECON_MIGRATION_PLAN.md # 从 pAI/MSc 迁移的设计记录
- ├── LICENSE
- ├── .claude/
- │ └── commands/
- │ ├── theoretical-economics-claude-skill.md # slash command 入口(默认模式)
- │ └── mode.md # /mode <模式名> 入口
- ├── model_library/ # 理论经济学典范模型库(仅结构模型)
- │ ├── consumer-choice.md
- │ ├── indirect-utility-expenditure-minimization.md
- │ ├── discrete-choice-random-utility.md
- │ ├── search-models.md
- │ ├── costly-information-acquisition.md
- │ ├── rational-inattention.md
- │ ├── signaling.md
- │ ├── screening.md
- │ ├── moral-hazard.md
- │ ├── adverse-selection.md
- │ ├── hotelling-product-differentiation.md
- │ ├── disclosure-persuasion-information-design.md
- │ ├── mechanism-design.md
- │ ├── matching-models.md
- │ ├── matching-with-cutoffs.md # Azevedo-Leshno (2016)
- │ ├── social-learning-information-cascades.md
- │ ├── dynamic-optimization-bellman.md
- │ ├── overlapping-generations-life-cycle.md
- │ ├── principal-agent.md
- │ ├── general-equilibrium-basics.md
- │ ├── political-economy-collective-choice.md
- │ ├── comparative-advantage-ricardian.md
- │ ├── heckscher-ohlin.md
- │ ├── new-trade-theory-krugman.md
- │ ├── melitz-firm-heterogeneity.md
- │ ├── dynamic-spatial-general-equilibrium.md # Kleinman-Liu-Redding (2023)
- │ ├── trade-labor-dynamics-china-shock.md # Caliendo-Dvorkin-Parro (2019)
- │ ├── io/
- │ │ ├── oligopoly-competition.md
- │ │ ├── entry-deterrence.md
- │ │ ├── two-sided-markets-platforms.md
- │ │ └── price-discrimination.md
- │ └── human_capital_and_labor/
- │ ├── becker-human-capital.md
- │ ├── ben-porath-lifecycle.md
- │ ├── roy-model.md
- │ ├── cunha-heckman-skill-formation.md
- │ ├── technology-of-skill-formation.md
- │ ├── self-productivity-dynamic-complementarity.md
- │ ├── early-childhood-investment.md
- │ ├── intergenerational-transmission.md
- │ ├── education-credit-constraints.md
- │ ├── occupational-choice-comparative-advantage.md
- │ ├── compensating-differentials.md
- │ ├── cobweb-supply-lags.md
- │ ├── task-based-production-acemoglu-restrepo.md
- │ ├── automation-displacement-reinstatement.md
- │ ├── human-capital-adaptation-automation-ai.md
- │ └── directed-technical-change-sbtc.md
- ├── settings.json # Claude Code 钩子注册(PreToolUse)
- ├── .claude/hooks/
- │ └── protect-files.sh # 产物保护钩子:禁止覆写 hypothesis.md 与已记录的验证产物
- ├── prompts/
- │ ├── entailment-ledger.md # 蕴含检查:九条链 + 支撑清单 + 可满足性(Gate 3/4/4R/6 共用)
- │ ├── verification-record.md # 逐命题验证记录的 schema 与状态规则
- │ ├── proof-code-independence.md # 证明—代码独立规则、I0–I4 分级、网格诚实性
- │ ├── mode-empirical-companion.md # empirical-companion 模式契约
- │ ├── ec-00-empirical-scope-lock.md # Stage 0-EC(仅 empirical-companion 模式)
- │ ├── ec-empirical-theory-map.md # 实证—理论映射与 minimality check
- │ ├── 00-intake.md
- │ ├── 01-puzzle-refinement.md
- │ ├── 02-literature-positioning.md
- │ ├── 02a-empirical-reality-check.md # Stage 2a + Gate 1b(现实契合度检查)
- │ ├── 03-persona-council.md
- │ ├── 03b-canonical-model-match.md
- │ ├── 04-model-primitives.md
- │ ├── 05-assumption-audit.md
- │ ├── 06-proposition-generator.md
- │ ├── 07-proof-sketch.md
- │ ├── 07b-numerical-simulation.md # 可选 Stage 7b(须用户明确选择)
- │ ├── 08-counterexample-finder.md
- │ ├── 09-economic-interpretation.md
- │ ├── 10-manuscript-skeleton.md
- │ ├── gate-01-novelty-risk.md
- │ ├── gate-02b-canonical-fit.md
- │ ├── gate-02c-theory-lineage.md
- │ ├── gate-02-model-coherence.md
- │ ├── gate-03-non-triviality.md
- │ ├── gate-04-proof-integrity.md
- │ ├── gate-04b-numerical-integrity.md # 可选 Gate 4b(仅当 Stage 7b 运行后)
- │ ├── gate-04r-revision-regate.md # Gate 4R 修订重过门(HiL-6 之后、Stage 9 之前)
- │ ├── gate-05-economic-meaning.md
- │ ├── gate-06-math-review.md # Gate 6 数学审查(编译 PDF 前)
- │ └── gate-ec-empirical-alignment.md # Gate EC(仅 empirical-companion 模式)
- ├── docs/
- │ ├── persona-council.md # Stage 3 说明
- │ ├── mode-empirical-companion.md # empirical-companion 模式说明
- │ ├── mode-empirical-companion-tests.md # 该模式的三项验证测试
- │ └── issue-001-pilot-feedback.md # 试用反馈记录
- ├── examples/ # 可用 --task 直接载入的示例输入
- │ ├── quickstart-task.txt
- │ ├── demo-human-capital-ai-automation.txt
- │ ├── demo-nutrition-label-attention.txt
- │ ├── demo-ec-clean-companion.txt # Test EC1 fixture
- │ ├── demo-ec-impossible-hypothesis.txt # Test EC2 fixture
- │ └── demo-ec-domain-reversal.txt # Test EC3 fixture
- ├── templates/
- │ ├── state.json
- │ ├── verification_record.json # 逐命题验证记录骨架
- │ ├── academic-econ.latex # 旧版 PDF 模板(已弃用,现直接写 .tex)
- │ ├── author_style_guide_econ.md
- │ └── author_style_guide_default.md
- ├── legacy/ # 原 pAI/MSc 流水线遗留文件(仅存档,非活跃流程)
- └── Exploration/ # 所有项目工作区(自动生成;已列入 .gitignore,
- └── Project_NNN_<ModelAbbrev>/ # 默认不提交,需公开时用 git add -f 手动上传)
- ```
- ---
- ## 适用与不适用
- ### 适用
- - 理论经济学早期构思
- - 经典模型扩展
- - 机制建模
- - 人力资本、劳动经济学、信息经济学、产业组织、行为经济学等理论问题
- - 工作论文初步框架
- - 命题和 proof sketch 的审查
- - 反例与边界情形检查
- ### 不适用
- - 真实数据清洗与实证分析
- - 自动完成严格数学证明
- - 自动确认文献 novelty
- - 自动生成可直接投稿的论文
- - 替代研究者做理论判断
- ---
- ## Contributing
- 欢迎围绕以下方向提交改进:
- - auction theory、macro、IO、political economy 等专题模型库
- - 更严格的 proof integrity gate
- - 更丰富的 counterexample templates
- - 更多 manuscript PDF 模板样式
- - explore mode:多轮理论模型空间探索
- 基本流程:
- ```text
- 1. Fork this repository
- 2. Edit prompt files, model_library, or SKILL.md routing logic
- 3. Test on a research hypothesis end-to-end
- 4. Submit a PR describing what changed and why
- 若改动涉及 empirical-companion 模式,请同时跑通 `docs/mode-empirical-companion-tests.md` 中的
- Test BC(向后兼容)、Test RT(模式路由)和 Test EC1–EC3,并把结果记入该文件末尾的表格。
- ```
- ---
- ## License
- MIT License.
- Copyright © 2026 Chen Zhu, Xiaolu Wang, Weilong Zhang.
- Based on pAI/MSc by Mahmoud Abdelmoneum, Pierfrancesco Beneventano, and Tomaso Poggio.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.