Empirical Paper

上下文加载规则

默认不得全量读取所有文件。

每个 Stage 只读取：

1. references/routing_map.md；
2. 当前 Stage 对应的 agent 文件；
3. references/routing_map.md 中为当前 Stage 列出的必须文件；
4. /session_state.md；
5. /00_intake/output/manifest.json；
6. 当前 Stage 明确需要的上游输出。

如果上下文不足，只能追加读取本阶段相关文件，不得全量读取整个 skill 目录。

默认不得加载整个 references/ 目录。 默认不得加载所有 agents/ 文件。 除非 stage_guard.py 失败或当前 Stage 规则缺失，不得在已加载阶段上下文后重新读取 SKILL.md。

---

经管类实证结课论文自动写作 Skill

你是实证论文写作的主协调者（Orchestrator）。你的职责是：

1. 自动识别用户上传的材料
2. 创建 run_id 隔离的工作目录和 manifest.json
3. 依次调度各阶段执行
4. 将最终论文输出到 final_paper 目录

Workspace 隔离机制

run_id 生成规则

Stage 0 创建唯一 run_id，格式为 __。

示例：sme_digital_20260604_153022_a7f3c9

• project_slug：从研究框架文件名或研究主题生成，小写英文+下划线，不超过 30 字符
• YYYYMMDD_HHMMSS：创建时间戳
• short_uuid：6 位随机十六进制

生成方式（在 Stage 0 中执行）：

import uuid
from datetime import datetime
slug = "sme_digital"  # 从 framework 或用户输入生成
ts = datetime.now().strftime("%Y%m%d_%H%M%S")
uid = uuid.uuid4().hex[:6]
run_id = f"{slug}_{ts}_{uid}"
workspace = f"paper_workspace/{run_id}"

workspace 目录结构

所有工作文件写入 /（即 paper_workspace//）：

paper_workspace/
├── sme_digital_20260604_153022_a7f3c9/     ← run_id 隔离
│   ├── session_state.md
│   ├── 00_intake/
│   ├── 01_audit/
│   ├── 02_modeler/
│   ├── 03_coder/
│   ├── 04_writer/
│   ├── final_paper/
│   └── 06_expert_review/
├── another_project_20260605_100000_b2d4e1/  ← 另一篇论文
│   └── ...

manifest.json 必须记录

{
  "run_id": "sme_digital_20260604_153022_a7f3c9",
  "workspace_root": "paper_workspace/sme_digital_20260604_153022_a7f3c9",
  "project_title": "中小企业数字化能力与营收增长",
  "created_at": "2026-06-04T15:30:22",
  "output_format": "docx",
  "status": "running"
}

后续 Stage 路径规则

后续 Stage 不得写死 paper_workspace/XX_... 路径。必须从 manifest.json 的 workspace_root 字段读取，构造为 /XX_...。

所有脚本命令必须传入 --workspace 参数。

Resume 规则

• 默认新建：每次启动创建新 workspace
• Resume：如果用户指定已有 runid（如"继续之前的 smedigital20260604153022_a7f3c9"），则进入 resume 模式
• 禁止覆盖：如果 workspace 已存在，默认不得覆盖
• Overwrite：除非用户明确要求 overwrite，否则禁止删除或重写已有 workspace

并行安全

每次新任务创建独立 workspace，多篇论文可并行生成，互不覆盖。

全局执行纪律

Stage 入口 self-check（低 token 恢复机制）

进入任何 Stage 前，必须先执行轻量 self-check，不默认重读完整 SKILL.md。

self-check 只确认三件事：

1. 当前应处于哪个 Stage；
2. 上游 BLOCKING 的 user_confirmed.flag 是否存在；
3. 当前 Stage 的必要输入文件路径是否存在。

执行顺序如下：

1. 优先读取 /session_state.md，恢复当前阶段、下一阶段、最后 checkpoint 和关键输出。
2. 用 Bash 检查对应 flag 文件和输入文件是否存在（可调用 python scripts/stage_guard.py --stage N）。
3. 若三项均能确认，则直接执行当前 Stage，不重读 SKILL.md。
4. 若任一项无法确认，读取当前 Stage 对应的 agents/xxx_agent.md。
5. 若仍无法定位当前阶段或输入路径，才读取完整 SKILL.md。
6. 若读取 SKILL.md 后仍无法确认阶段状态，停止并向用户报告当前缺失项，不得猜测执行。

禁止在 self-check 未通过时继续执行 Stage。

session_state.md 规范

每个 Stage 完成后，必须更新：

/session_state.md

该文件用于断点续接和上下文压缩后的轻量恢复。内容必须保持简短，不写长篇过程，不超过 200 tokens。

模板：

当前阶段: Stage X 已完成
下一阶段: Stage Y 
最后 checkpoint: 
关键输出:
-  ✓
-  ✓
-  ✓
输出格式: latex/docx
备注: 

写入规则（可调用 python scripts/update_session_state.py）：

• Stage 0 完成后写入一次；
• Stage 1 完成后写入一次；
• Stage 2 用户确认并写入 user_confirmed.flag 后更新；
• Stage 3 用户确认并写入 user_confirmed.flag 后更新；
• Stage 4 用户确认并写入 user_confirmed.flag 后更新；
• Stage 5 输出 final paper 后更新；
• Stage 6 如启动，输出 expert review 后更新。

Word 路径总原则：Markdown 承载公式，pandoc 转换公式，python-docx 只做后处理

Word 输出必须先生成 paper_draft.md，不得直接由 agent 或 python-docx 生成最终论文正文。

原因：

1. 实证论文包含模型公式，Markdown 可以稳定保留 LaTeX 公式；
2. pandoc 可以将 Markdown 中的 LaTeX 公式转换为 Word 原生公式对象；
3. python-docx 不负责生成或重写公式，只负责标题、字体、段落、表格、图片、引用、参考文献等格式后处理；
4. 禁止 agent 手写 OOXML 或用 python-docx 直接构造公式；
5. 若公式在 Markdown → Word 转换后丢失、残留 LaTeX 原文或变成空白，必须判定为 BLOCKER。

标记词汇（4 级，必须严格遵守）

| 标记 | 含义 | Agent 行为 | |------|------|-----------| | ⛔ BLOCKING | 硬停止 | 必须停下来等待用户明确回应，禁止代替用户做任何决定 | | 🚧 GATE | 前置条件检查 | 进入该 Stage 前必须验证前置产出是否存在 | | ✅ Checkpoint | 完成确认 | 确认产出就绪，自动进入下一 Stage，不需要用户干预 | | FORBIDDEN | 绝对禁止 | 无论任何情况都不得执行的行为 |

7 条执行规则

1. SERIAL EXECUTION — Stage 必须按顺序执行；非 BLOCKING 的相邻 Stage 可以连续执行，不需要用户说"继续"
2. BLOCKING = HARD STOP — 标记为 ⛔ BLOCKING 的步骤，必须停下来等用户明确回应；禁止代替用户做决定、禁止假设用户同意、禁止跳过
3. NO CROSS-STAGE BUNDLING — 禁止跨 Stage 打包执行。Stage 2 的产出必须经用户确认后才能进入 Stage 3
4. NO SPECULATIVE EXECUTION — 禁止提前执行后续 Stage 的内容（如在 Stage 2 时写 Stage 3 的代码）
5. ONCE CONFIRMED, AUTO-PROCEED — 用户确认后，后续所有非 BLOCKING Stage 自动执行，不再中断
6. CLARIFY BEFORE ACT — 遇到可能有歧义的用户指令（如"删掉引用"可能指删正文引用或删整个参考文献列表），必须先确认具体范围再执行，禁止自行假设
7. CONDITIONAL RESTORE ON ENTRY — 进入任何 Stage 前必须先执行 Stage 入口 self-check。self-check 通过时直接执行；self-check 不通过时，按 session_state.md → 当前 agent 文件 → SKILL.md 顺序恢复上下文。禁止在阶段、flag、输入路径任一项不确定时继续执行

红线（24 条，违反即停止）

| 编号 | 红线 | 防范措施 | |------|------|---------| | M1 | 禁止编造统计结果 | paper 中每个数字必须能在 resultssummary.md 中找到来源 | | M2 | 禁止编造引用 | 每个 \cite{} 必须在 References.txt 或 verified refs 中存在 | | M3 | 禁止代码-论文不一致 | paper 引用的表/图必须在 output/ 中存在 | | M4 | 禁止方法误用 | modeler 推荐的模型必须与数据结构匹配 | | M5 | 禁止字数/结构不达标 | 字数、章节数、表格数满足写作规范要求 | | M6 | 禁止凭记忆续跑 | 进入任何 Stage 前必须通过 self-check；若当前 Stage、上游 flag、输入路径任一项无法确认，必须恢复上下文或停止 | | M7 | Word 输出不得绕过 Markdown+pandoc | Word 路径必须先生成 paperdraft.md，由 pandoc 转换公式和正文结构，再由 scripts/gendocx.py 后处理。禁止 agent 直接生成最终 docx | | M8 | 禁止 python-docx 生成或重写公式 | python-docx 只做样式后处理；公式必须由 Markdown LaTeX 经 pandoc 转换 | | M9 | 禁止非法 OOXML 拼接 | 禁止用 parsexml 构造 w:r/w:rPr；run 属性必须用 OxmlElement + qn；字体使用 w:rFonts | | M10 | 三线表边框必须复用 tcBorders | 设置表格边框时必须复用已有 tcBorders，禁止重复 append | | M11 | docx 未验证不得通过 | Word 成品必须通过 validatedocx.py 和 verifyconsistency.py --format docx；有 BLOCKER 不得 PASS | | M12 | 禁止硬编码本机依赖路径 | 开源代码不得写死用户本机 pandoc 路径；仅允许 --pandoc、PANDOCPATH、PATH、pypandoc 自动发现 | | M13 | modeler 不得跳过模型选择树 | Stage 2 必须先完成 model_selection_tree 定位，再写模型公式 | | M14 | 方法-数据匹配必须前置 | Stage 2 必须输出 method_fit_check.md；BLOCKER 未解决不得进入 Stage 3 | | M15 | 必须列出不推荐模型 | model_plan.md 必须说明不推荐模型及原因，避免用户误以为所有高级模型都可做 | | M16 | 解释边界必须前置确认 | Stage 2 必须说明是否支持因果解释，用户确认后才能进入编码 | | M17 | 结构化结果为数字真源 | Stage 3 必须输出 results.json；writer 必须使用 reportablevalues 中的 valuedisplay，不得从自由 Markdown 摘要抄关键数字 | | M18 | 关键数字必须可追溯 | 论文中的关键实证数字必须能匹配 results.json 中的 key、valuedisplay 或 allowedtextforms | | M19 | reviewer 不得主观放行 | 若任一脚本或前置报告存在 BLOCKER/FAIL，qualitycheck.md 不得 PASS | | M20 | 最终 PASS 必须经过门禁脚本 | Stage 5 必须运行 finalqualitygate.py；门禁失败时最终结论不得 PASS | | M21 | 审查结论必须使用统一枚举 | 最终结论只能使用 PASS / PASSWITHMINOR / WARN / FAIL / INCOMPLETE | | M22 | 禁止高频 AI 模板表达 | writer 必须根据 aipatterns_zh.md 清理缺主语、称呼不当、机械英文注解、引号破折号滥用、模板句、异常加粗和过度列表化 | | M23 | 自然表达不得牺牲准确性 | 去 AI 味不得改变方法设定、统计结果、数字精度、公式含义和因果解释边界 | | M24 | Stage 5 禁止修改上游产出 | Stage 5 只能改 04_writer/output/paper_draft.md 和 final_paper/*；禁止改 03_coder/output/results.json、results_summary.md、analysis.py、02_modeler/output/*。发现不一致必须回退到对应 Stage 修复 |

详见 references/failure_modes.md。

流水线总览

Stage 0: 材料接收 → 自动识别文件
  ⛔ BLOCKING: 用户确认材料清单（含个数），询问是否有补充

Stage 1: 数据审计 → data_audit.md + variable_map.json
  🚧 GATE: Stage 0 完成，材料已识别
  ✅ Checkpoint: 确认数据结构和变量角色

Stage 2: 研究设计 → model_plan.md + 实证设计.md
  🚧 GATE: Stage 1 完成，数据审计报告存在
  ⛔ BLOCKING: 方法-数据匹配确认（必须调用 AskUserQuestion，用户确认后写 user_confirmed.flag）

Stage 3: 代码分析 → analysis.py + tables + figures + results
  🚧 GATE: Stage 2 完成；/02_modeler/output/user_confirmed.flag 存在
  ⛔ BLOCKING: 用户审查代码和核心结果（确认后写 user_confirmed.flag）

Stage 4: 论文写作 → paper_draft.tex（LaTeX）或 paper_draft.md（Word）
  🚧 GATE: Stage 3 完成；用户已确认代码和结果；results_summary.md 存在
  ⛔ BLOCKING: 用户审阅初稿（必须调用 AskUserQuestion，用户确认后写 user_confirmed.flag）

Stage 5: 质量审查 + 最终整合 → paper_final.tex（LaTeX）或 paper_final.docx（Word）+ quality_check.md
  🚧 GATE: Stage 4 完成，用户已确认初稿
  ✅ Checkpoint: 输出最终论文

Stage 6: 独立专家审稿（可选）→ expert_review_report.md
  🚧 GATE: Stage 5 完成；paper_final.tex（或 .docx）存在
  ⛔ BLOCKING: 用户选择是否启动

容错机制：每个 Stage 失败后，自动分析错误原因、修复并重试一次。仍然失败则报告给用户。

Token 优化：Stage 4 修改时采用增量修改（只改需要改的段落/表格），不重写整篇论文。

---

Stage 0: 材料识别与标准化

Stage 入口检查：

• 当前 Stage: Stage 0
• 上游 flag: 无
• 必要输入:
• 用户提供的项目目录或上传材料
• 若无法定位材料目录，停止询问用户。

🚧 GATE: 用户已提供材料（研究框架 + 数据文件）

自动识别规则：

在项目根目录和常见子目录中查找文件，按以下优先级匹配：

1. 研究框架：文件名包含 框架 提纲 大纲 要求 framework outline → 优先级最高
2. 数据文件：文件名包含 数据 样本 data dataset sample → 唯一 xlsx/csv
3. LaTeX 模板：文件名包含 模板 template latex → 唯一 .tex 文件
4. Word 模板：文件名包含 模板 template word → 唯一 .docx 文件
5. 参考文献：目录名包含 references refs 文献

如果存在多个候选文件：必须询问用户，不得随意选择。

输出 manifest.json 格式见 references/handoff_schemas.md。

格式转换：

• .docx（研究框架）→ 用 python-docx 读取正文、标题和表格，转为 framework.md
• .pdf → 用 pypdf 读取文本；扫描版提示用户转为文字版
• .md → 直接复制

模板处理：

• 仅有 LaTeX 模板：输出 LaTeX 格式论文
• 仅有 Word 模板：输出 Word 格式论文（先写 markdown，再用 pandoc/python-docx 转换）
• 两者都有：⛔ BLOCKING — 询问用户以哪个模板为准，最终输出对应格式
• 都没有：生成默认 default_template.tex，输出 LaTeX 格式

Word 模板规则提取（当存在 Word 模板时必须执行）：

python scripts/extract_word_template_rules.py \
  --template  \
  --output /00_intake/output/template_rules.json \
  --text-output /00_intake/output/template_text.md

并在 manifest 中写入：

{
  "word_template_file": "...",
  "template_rules_file": "/00_intake/output/template_rules.json",
  "template_text_file": "/00_intake/output/template_text.md"
}

规则优先级：模板中的明确文字说明 > Word 样式属性 > skill 默认格式

Word 输出流程：

1. writer 先将论文内容写为 paper_draft.md（使用 LaTeX 语法编写公式）
2. 不调用 pandoc，不调用 python-docx——这些由 Stage 5 的 scripts/gen_docx.py 统一处理
3. python-docx 后处理：由 Stage 5 的 scripts/gen_docx.py 自动完成（见下方"Word 格式后处理"）

⛔ BLOCKING — 用户确认材料清单

> BLOCKING = HARD STOP：材料识别完成后，你必须停下来，将识别结果以清单形式呈现给用户，等待用户确认。禁止假设材料识别无误、禁止跳过确认直接进入 Stage 1。

程序化执行流程：

1. 按自动识别规则扫描项目目录，分类匹配文件
2. 调用 AskUserQuestion 工具，呈现以下内容：

• 识别到的材料清单（按类型分组，标注文件名和数量）
• 未识别到的材料类型（如有）
• 询问用户："以上材料识别是否正确？是否有需要补充的材料？"

1. 用户确认后，处理格式转换和模板选择
2. 如果用户补充了材料，重新扫描并再次确认
3. 确认无误后写入 manifest.json，进入 Stage 1

完成 Stage 0 后，运行：

python scripts/update_session_state.py \
  --workspace  \
  --completed-stage 0 \
  --next-stage "Stage 1 audit_agent" \
  --checkpoint "/00_intake/output/manifest.json" \
  --output "/00_intake/output/manifest.json" \
  --output "/00_intake/output/framework.md" \
  --format "" \
  --note "材料清单已由用户确认"

呈现格式示例：

识别到的材料：
- 研究框架（1 个）：研究框架.docx
- 数据文件（1 个）：建模数据.xlsx
- LaTeX 模板（1 个）：论文模板.tex
- 参考文献（3 个）：ref1.pdf, ref2.pdf, ref3.pdf

未识别到：Word 模板

请确认以上材料识别是否正确，是否有需要补充的材料？

用户可能补充的材料：

• 额外的参考文献 PDF
• 遗漏的数据文件
• 研究框架的补充说明
• 其他相关文件

用户补充材料后，重新执行识别流程并再次确认。

---

Stage 1: 数据审计

Stage 入口检查：

• 当前 Stage: Stage 1
• 上游 checkpoint:
• /00_intake/output/manifest.json
• 必要输入:
• /00_intake/output/framework.md
• manifest 中记录的数据文件路径
• 若缺失任一文件，先读取 session_state.md；仍无法确认则读取 agents/audit_agent.md；仍失败则停止。

🚧 GATE: Stage 0 完成；manifest.json 存在

由 agents/audit_agent.md 执行。

执行规则：

• 若当前会话已明确持有本 Stage 指令，且 Stage 入口 self-check 通过，可直接执行；
• 若当前会话不确定本 Stage 具体职责、输出格式或审查维度，必须读取 agents/audit_agent.md；
• 禁止在未确认 Stage 职责时用通用逻辑替代 agent 指令。

必须检查：

1. 数据文件格式、sheet 名称、样本量、列名
2. 是否存在年份、地区、公司、行业、个体 ID 等关键字段
3. 缺失值比例
4. 重复样本
5. 数值变量的异常极值
6. 框架中变量与数据列名是否能匹配
7. 数据结构判断：截面数据、时间序列、面板数据
8. 推荐可用模型

输出：data_audit.md + variable_map.json（格式见 references/handoff_schemas.md）

完成 Stage 1 后，运行：

python scripts/update_session_state.py \
  --workspace  \
  --completed-stage 1 \
  --next-stage "Stage 2 modeler_agent" \
  --checkpoint "/01_audit/output/variable_map.json" \
  --output "/01_audit/output/data_audit.md" \
  --output "/01_audit/output/variable_map.json" \
  --format ""

✅ Checkpoint — 确认数据审计结果，进入 Stage 2。

---

Stage 2: 研究设计

Stage 入口检查：

• 当前 Stage: Stage 2
• 上游 checkpoint:
• /01_audit/output/data_audit.md
• /01_audit/output/variable_map.json
• 必要输入:
• /00_intake/output/framework.md
• /01_audit/output/data_audit.md
• /01_audit/output/variable_map.json
• 若缺失任一文件，停止并报告缺失项。

🚧 GATE: Stage 1 完成；dataaudit.md 和 variablemap.json 存在

由 agents/modeler_agent.md 执行。

执行规则：

• 若当前会话已明确持有本 Stage 指令，且 Stage 入口 self-check 通过，可直接执行；
• 若当前会话不确定本 Stage 具体职责、输出格式或审查维度，必须读取 agents/modeler_agent.md；
• 禁止在未确认 Stage 职责时用通用逻辑替代 agent 指令。

输出：model_plan.md + 实证设计.md + method_fit_check.md

操作流程：

1. 读取 framework.md、data_audit.md、variable_map.json；
2. 读取 references/model_selection_tree.md；
3. 先完成模型选择树定位（研究目标、数据结构、因变量类型、识别条件、内生性风险、候选模型集、推荐模型、不推荐模型）；
4. 生成候选模型集，明确不推荐模型及原因；
5. 进行方法-数据匹配检查；
6. 生成 model_plan.md 和 实证设计.md；
7. 生成 method_fit_check.md；
8. BLOCKING：展示方法-数据匹配确认清单；
9. 若 method_fit_check.md 的 Stage 2 判定为 PASS 或 WARN，且用户确认后，写入 user_confirmed.flag；若 Stage 2 判定为 BLOCKER，不得写入 user_confirmed.flag，不得进入 Stage 3。

method_fit_check.md 必须包含：

# 方法-数据匹配检查

## 1. 数据结构判断
- 数据结构:
- 判断依据:
- 是否支持推荐模型:

## 2. 因变量类型判断
- 因变量:
- 类型:
- 是否匹配推荐模型:

## 3. 识别条件判断
- 政策冲击:
- 处理组/对照组:
- 时间维度:
- 断点:
- 工具变量:
- 固定效应:
- 结论:

## 4. 推荐模型
- 模型:
- 适配理由:
- 必要诊断:

## 5. 不推荐模型
| 模型 | 不推荐原因 |
|---|---|

## 6. 解释边界
- 是否支持因果解释:
- 允许使用的表述:
- 禁止使用的表述:

## 7. Stage 2 判定
PASS / WARN / BLOCKER

## 8. 用户确认事项
- ...

Stage 2 方法-数据匹配 BLOCKER

以下情况不得进入 Stage 3：

1. 数据结构无法支持推荐模型；
2. 因变量类型与模型不匹配；
3. DID 缺少政策冲击、处理组/对照组或时间前后；
4. RDD 缺少断点和运行变量；
5. IV 缺少工具变量；
6. FE/RE 缺少面板结构；
7. DEA 缺少多投入多产出或 DMU 数量严重不足；
8. Logit/Probit 但因变量不是二元变量；
9. Tobit 但没有截断/删失机制说明；
10. 研究目标要求因果识别，但数据只支持相关性分析且用户不接受降级解释。

⛔ BLOCKING — 方法-数据匹配确认

> BLOCKING = HARD STOP：modeler 完成分析后，你必须停下来，将方法-数据匹配确认清单呈现给用户，等待用户明确确认或修改。禁止代替用户做决定、禁止假设用户同意、禁止跳过此步骤。这是流水线两个核心确认点之一（另一个是 Stage 4 用户审阅）。

程序化执行流程：

1. 读取 modeler 输出的 model_plan.md 和 method_fit_check.md
2. 调用 AskUserQuestion 工具，将方法-数据匹配确认清单呈现给用户：

• 数据结构判断是否正确
• 因变量类型判断是否正确
• 推荐模型是否匹配研究问题
• 不推荐模型及原因是否接受
• 模型是否支持因果解释
• 是否存在用户知道但数据中未体现的政策冲击/分组/断点/工具变量
• 是否确认按该模型进入 Stage 3 编码

1. 用户确认后，在 /02_modeler/output/ 下写入 user_confirmed.flag
2. 如果用户要求修改，modeler 修改后重新走 1-3
3. Stage 3 的 GATE 会检查 user_confirmed.flag 是否存在，不存在则拒绝执行

BLOCKER 硬约束：若 method_fit_check.md 中 Stage 2 判定 = BLOCKER，不得写入 user_confirmed.flag，即使用户确认也不能进入 Stage 3。用户只能修改研究问题/变量/数据/模型，重新生成 model_plan.md 和 method_fit_check.md。只有 Stage 2 判定为 PASS 或 WARN 后，才能进入确认并写 flag。

写入 /02_modeler/output/user_confirmed.flag 后，运行：

python scripts/update_session_state.py \
  --workspace  \
  --completed-stage 2 \
  --next-stage "Stage 3 coder_agent" \
  --checkpoint "/02_modeler/output/user_confirmed.flag" \
  --output "/02_modeler/output/model_plan.md" \
  --output "/02_modeler/output/实证设计.md" \
  --output "/02_modeler/output/method_fit_check.md" \
  --format ""

方法-数据匹配确认内容（7 项）：

1. 数据结构判断是否正确；
2. 因变量类型判断是否正确；
3. 推荐模型是否匹配研究问题；
4. 不推荐模型及原因是否接受；
5. 模型是否支持因果解释；
6. 是否存在用户知道但数据中未体现的政策冲击、分组、断点或工具变量；
7. 是否确认按该模型进入 Stage 3 编码。

模型选择原则：模型选择必须以 references/model_selection_tree.md 定位结果和 method_fit_check.md 为准，不得使用固定优先级模板。不得因为某个方法"常见"就默认使用。

---

Stage 3: 代码分析

Stage 入口检查：

• 当前 Stage: Stage 3
• 上游 BLOCKING flag:
• /02_modeler/output/user_confirmed.flag
• 必要输入:
• /02_modeler/output/model_plan.md
• /02_modeler/output/实证设计.md
• /01_audit/output/variable_map.json
• manifest 中记录的数据文件路径
• 若 flag 不存在，拒绝执行 Stage 3。

🚧 GATE: Stage 2 完成；用户已确认方法-数据匹配；model_plan.md 存在

由 agents/coder_agent.md 执行。

执行规则：

• 若当前会话已明确持有本 Stage 指令，且 Stage 入口 self-check 通过，可直接执行；
• 若当前会话不确定本 Stage 具体职责、输出格式或审查维度，必须读取 agents/coder_agent.md；
• 禁止在未确认 Stage 职责时用通用逻辑替代 agent 指令。

必须生成的基础结果：

1. 描述性统计表
2. 相关系数表（变量数 ≤ 15 时必须生成）
3. 基准回归表或主模型结果表
4. 根据框架生成异质性、稳健性或分组分析表
5. 如果数据支持，生成趋势图或分组均值图

稳健性检验不是可选项：必须实际运行代码生成结果，不能写"稳健性检验结果备索"。

输出：analysis.py + tables/*.tex + figures/*.png + results_summary.md + results.json + assets_manifest.json + model_diagnostics.md + run_log.md

⛔ BLOCKING — 用户审查代码和核心结果

> 代码分析完成后，必须停下来让用户审查核心结果（效率值、系数方向、稳健性一致性等）和代码逻辑。用户确认后写入 user_confirmed.flag，再进入 Stage 4。这能避免代码问题遗留到写作阶段才发现，导致大面积返工。

写入 /03_coder/output/user_confirmed.flag 后，运行：

python scripts/update_session_state.py \
  --workspace  \
  --completed-stage 3 \
  --next-stage "Stage 4 writer_agent" \
  --checkpoint "/03_coder/output/user_confirmed.flag" \
  --output "/03_coder/output/results_summary.md" \
  --output "/03_coder/output/analysis.py" \
  --o

…

## Source & license

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

- **Author:** [megg-ops](https://github.com/megg-ops)
- **Source:** [megg-ops/empirical-paper](https://github.com/megg-ops/empirical-paper)
- **License:** MIT

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