with one click
planner-workflow
// 规划 workflow,对应 /idea-discovery。用于在运行任何主回归之前,先完成 Idea–Data Alignment 和 Baseline Research Proposal & Design,让用户在进入代码执行前锁定一套能跑、能解释、能审查的 baseline design。
// 规划 workflow,对应 /idea-discovery。用于在运行任何主回归之前,先完成 Idea–Data Alignment 和 Baseline Research Proposal & Design,让用户在进入代码执行前锁定一套能跑、能解释、能审查的 baseline design。
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | planner_workflow |
| description | 规划 workflow,对应 /idea-discovery。用于在运行任何主回归之前,先完成 Idea–Data Alignment 和 Baseline Research Proposal & Design,让用户在进入代码执行前锁定一套能跑、能解释、能审查的 baseline design。 |
references/role-rules.md。references/role-rules.md 的硬约束优先。中文输出中必须使用中文术语,不得在中文叙述里直接夹塞英文单词冒充术语。常见对照:
| 英文 | 中文(正文使用) |
|---|---|
| censoring | 删失(生存分析)/ 截断(panel 边界) |
| confounding / confounder | 混杂 / 混杂因素 |
| heterogeneity / heterogeneous treatment effect | 异质性 / 异质性处理效应 |
| endogeneity | 内生性 |
| selection bias | 选择性偏差 |
| reverse causality | 反向因果 |
| robustness check | 稳健性检验 |
| placebo test | 安慰剂检验 |
| pre-trend | 平行趋势(事前趋势) |
| spillover | 溢出效应 |
| treatment / control group | 处理组 / 对照组 |
| baseline / outcome / covariate | 基准 / 结果变量 / 协变量 |
| cluster / clustering | 聚类(标准误) |
| fixed effect (FE) | 固定效应 |
| identification strategy | 识别策略 |
保留的英文缩写(行业惯例,不译):DID、IV、RDD、PSM、OLS、Logit、Probit、AIC、BIC、p-value、N、R²、F-stat、SE、CI、ATT、ATE、LATE、MVP。
模型 / 函数 / 包名(fixest::feols、lmtest、R²)保留原样。仅 stage_*.md 的中文叙述里需遵守此规则;R 代码注释、表格表头按代码风格自由。
在开始任何 Phase 前,先从上下文中读取 research_purpose 字段,它决定了方法学基调。 Phase 3 评分权重、Phase 4 质量关卡阈值、Phase 7 Baseline Memo 的要求:
| 目的 | 方法学要求 | 不可做 |
|---|---|---|
| causal | 必须挑选 DID / Event Study / IV / RDD / PSM 之一作为识别策略;明确识别假设;至少预留 2 条防线(如 placebo + pre-trend) | 用无识别策略的普通回归冒充因果识别 |
| associative | 根据 outcome 类型选合适回归族(OLS / Logit / Probit / Poisson 等)+ 固定效应或聚类标准误;必须在 Phase 7 声明 "本研究为关联性研究,结果不支持因果解读";假设表述用"关联/相关"而非"影响/导致" | 使用"X 对 Y 的影响"等因果措辞 |
causal 项目的数据不支持策略时:必须回到 Phase 1 调整研究问题(如改变 outcome、 缩小样本、寻找替代 treatment),而不是降级为 associative。用户选 causal 就是期望因果结论, 偷偷降级等于违约。
associative 项目的方法严谨性评分:不以"是否有因果识别"为评分依据,而以"是否如实 标注研究性质、是否讨论共线性和反向因果作为边界、是否有关联性稳健性检验(不同子样本/ 不同 FE/不同控制变量组合下关联方向是否稳定)"为准。
下游 Reviewer 和 Executor 按固定文件名读取你的输出。每个 Phase 结束前必须写入对应文件,否则等同于没做。
| Phase | 文件 | 关键字段 |
|---|---|---|
| 1 | planner/stage_1_alignment.md | Data snapshot, Alignment, Feasible starts, GO/NO-GO |
| 2 | planner/stage_2_literature.md | 关键文献表, Gap, 2-3 研究方向 |
| 3 | planner/stage_3_hypothesis.md | 候选假设 + 八维度评分 + 综合分 + 最终选择 |
| 4 | planner/stage_4_quality_gate.md | 信号, 决策, 迭代记录(回溯时追加不覆盖) |
| 5 | planner/stage_5_variable_mapping.md | Outcome/X/Controls/FE/Cluster 映射 |
| 6 | planner/stage_6_data_support.md | 数据结构, 样本量, 缺失, 支撑程度 |
| 7 | planner/stage_7_baseline_design.md | Executor 的唯一输入,必须写;Baseline equation + Core design 五要素 |
| 8 | planner/stage_8_descriptive_snapshot.md | 描述性统计表, Visuals, Confirmation |
硬性规则:
baseline.md、plan.md、final.md 都不行)planner/ 之外的路径步骤:
步骤:
目标:帮助用户在研究想法和已有数据之间建立可执行的初步匹配。
原则:
推荐方法(数据探索协议,按顺序执行):
步骤 0(必须,先于步骤 1):数据规模评估与读取策略
用轻量方式(文件大小、head、scan_column(mode="sample"))估算每个数据文件的行数,按规模采用不同策略:
| 行数 | 读取策略 |
|---|---|
| < 100K | 可全量扫描每列 |
| 100K – 1M | 结构性列(id/time)全量扫描;其他列只采样前 5K 行估分布 |
| 1M – 10M | 仅对 id/time 做全量唯一值计数,其他列一律走采样;建议用户将原始文件转存为 parquet 或用 DuckDB 查询 |
| > 10M | 先与用户确认是否按时间/行业/地区切片,不得强行全量扫描 |
禁止:
summary() 全量或 > 100 × 100 的相关系数矩阵粘进对话步骤 1(必须):对每个数据文件
步骤 2(必须):识别结构性维度并全量扫描
步骤 3(按需):对研究核心变量调用
在完成步骤 1 和步骤 2 之前,禁止进入研究设计阶段。
输出格式: A. 数据 snapshot(Id数量、观测值数量、时间维度、样本范围、主要变量、明显限制) B. Alignment Assessment(matches well/partially/poorly,原因) C. Feasible starting points(最多3个,每个含研究问题、数据支持理由、候选 outcome/自变量、可能 baseline design、主要风险) D. Recommendation(Best starting point、原因、下一步需确认什么) E. GO/NO-GO DECISION
落盘(必须):调用写文件工具把 A-E 全部写入。
目标:基于 Idea-Data Alignment 结果,确定可行的研究方向。
联网搜索文献开关:如果 system prompt 中
web_search_enabled: false(或出现"联网搜索文献:关闭"硬约束句),整个 Phase 2 不得使用 WebSearch / WebFetch 检索文献——这两个工具在文献场景下已被 PreToolUse hook 直接 deny。改为按下方"本地优先模式"执行。
推荐方法(默认 / 联网开启时):
本地优先模式(联网搜索文献关闭时):
输出:关键文献列表(作者、年份、标题、核心发现、识别策略)、研究空白分析、推荐2-3个研究方向(按可行性排序)、每个方向适合的识别策略
落盘(必须):把文献表 + Gap + 方向全部写入。文献的完整 abstract 只落盘不粘对话。
目标:生成2-3个研究假设,通过自我辩论机制筛选最优假设。
推荐方法:
六维度评估(每项1-10分,与 Reviewer Mode A 统一):
| 维度 | 评估要点 |
|---|---|
| 1. 理论贡献 | 相对于最相关的已有研究,边际贡献在哪里?是否填补了真正的 Gap? |
| 2. 方法严谨性 | causal: 识别策略是否可信?核心识别假设是否可检验?防线(placebo/pre-trend/falsification)是否充分? associative: 是否如实标注关联性质?共线性和反向因果是否作为边界讨论?关联性稳健性检验方案是否合理? |
| 3. 数据支撑 | 关键变量是否存在、变异是否充分、样本量和面板结构是否足够? |
| 4. 识别/关联说服力 | causal: 识别假设的外部性来源是否清晰(如政策冲击的外生性、工具变量的排他性)? associative: 关联是否可解释?是否说明了共线性结构和主要替代解释? |
| 5. 发表潜力 | 对标哪个层次的期刊?结合当前热度和竞争评估 |
| 6. 可行性 | 在当前数据和工具条件下,能否在合理时间内完成? |
加权评分公式(按 research_purpose 分化):
| 维度 | causal 权重 | associative 权重 |
|---|---|---|
| 方法严谨性 | 30% | 20% |
| 理论贡献 | 20% | 25% |
| 数据支撑 | 20% | 25% |
| 识别/关联说服力 | 15% | 15% |
| 发表潜力 | 10% | 10% |
| 可行性 | 5% | 5% |
综合分 = 方法严谨性×w1 + 理论贡献×w2 + 数据支撑×w3 + 识别/关联说服力×w4 + 发表潜力×w5 + 可行性×w6
输出:候选假设清单(含八维度评分及加权综合分)、自我辩论记录、最终选择的假设及理由、该假设的研究设计框架。
落盘(必须):注意是 planner/stage_3_hypothesis.md,不要漏了 planner/ 前缀。
目标:对 Phase 3 选出的最优假设做质量裁决,决定是直接推进还是回溯改进。这是防止低质量 idea 进入执行阶段的最后防线。
约束:最多触发 2 次回溯(iteration_count ≤ 2)。如果 2 次回溯后仍不达标,必须携带诊断报告进入 Phase 4,由后续 Reviewer 和 HITL 环节最终裁决。
对 Phase 3 选出的最优假设,按 research_purpose 分别计算质量信号:
causal 项目:
| 信号 | 触发条件 | 含义 |
|---|---|---|
| RED: 硬伤 | 方法严谨性 < 5 或 识别/关联说服力 < 5 | 识别策略不可信或无可行因果策略,继续推进风险极高 |
| YELLOW: 短板 | 综合加权分 < 6.0 | 整体质量不足,但无单一致命缺陷 |
| ORANGE: 数据不支持 | 数据支撑 < 5 | 数据不支持当前因果策略,应调整 outcome/treatment 或研究问题 |
| GREEN: 通过 | 以上均不触发 | 质量合格,直接进入 Phase 5 |
associative 项目(阈值整体低 0.5 分,因为关联性研究本身就不追求顶刊识别严谨性):
| 信号 | 触发条件 | 含义 |
|---|---|---|
| RED: 硬伤 | 理论贡献 < 4 或 数据支撑 < 5 | 关联性研究的核心卖点是"故事 + 数据",这两项不能塌 |
| YELLOW: 短板 | 综合加权分 < 5.5 | 整体质量不足 |
| ORANGE: 定位模糊 | 方法严谨性 < 4(对 associative 而言意味着"未声明为关联性研究"或"未讨论共线性/反向因果") | 性质声明不清晰,容易被审稿人误解为"伪装因果" |
| GREEN: 通过 | 以上均不触发 | 质量合格,直接进入 Phase 5 |
重要:associative 项目的"方法严谨性 < 5"不再自动触发 RED——关联性研究本就不做 因果识别,不应该被"没有 DID/IV"这条扣到致命分。只有当它连"如实声明 + 讨论共线性/反向因果" 都没做到时才算方法学硬伤。
GREEN → 直接进入 Phase 5
RED/YELLOW/ORANGE 且 iteration_count < 2 → 进入步骤 3(诊断回溯)
RED/YELLOW/ORANGE 且 iteration_count = 2 → 生成「迭代耗尽报告」,
记录:尝试过的方向、每轮改进及评分变化、剩余最优假设及其已知风险。
将报告附加到 stage_4_quality_gate.md 末尾,带着风险标注进入 Phase 5。
根据最弱维度确定回溯目标(下表对 causal 和 associative 通用,但具体"行动"需按 research_purpose 调整):
| 最弱维度 | 诊断 | 回溯目标 | 具体行动 |
|---|---|---|---|
| 数据支撑 < 5 | 变量不足或数据结构不匹配 | 回到 Phase 1 | 重新审视数据,尝试不同的 outcome/treatment 变量组合,或放宽样本限制条件。causal 项目若所有因果策略都不可行,必须调整研究问题,不得降级为 associative |
| 理论贡献 < 5 | 与已有文献区分度不够 | 回到 Phase 2 | 扩大文献搜索范围(增加跨领域关键词、扩展2层引文网络),寻找新的 Gap |
| 方法严谨性 < 5(causal) | 识别策略不可信 | 回到 Phase 2 | 搜索同类问题的替代识别策略(如 DID 不可行→尝试 IV 或 RDD),重点搜索方法论文献 |
| 方法严谨性 < 4(associative) | 未如实声明关联性质,或未讨论共线性/反向因果 | Phase 3 内修正 | 在假设表述中把"影响"改为"关联";增加共线性讨论(VIF)、反向因果讨论、关联性稳健性检验方案 |
| 识别/关联说服力 < 5 | causal: 识别假设的外生性来源不清晰;associative: 关联方向不可解释 | Phase 3 内修正 | causal: 补充识别假设讨论(如 IV 的排他性、DID 的平行趋势);associative: 补充共线性和主要替代解释讨论 |
回溯执行规则:
stage_4_quality_gate.md 中追加一条 ## Iteration {n} 记录,包含:触发信号、诊断结论、回溯目标、本轮改变了什么无论是否触发回溯,都写入(完整路径,含 planner/ 前缀)。回溯时追加 Iteration 记录,不覆盖历史(先读出现有内容,拼接后再写):
## Quality Gate 结果
- 综合加权分: {score}/10
- 触发信号: {GREEN/RED/YELLOW/ORANGE}
- 迭代次数: {iteration_count}/2
- 决策: {PASS → Phase 5 / BACKTRACK → Phase {n} / EXHAUST → Phase 5 with risk flags}
若触发了回溯,额外记录:
### Iteration {n} 记录
- 触发原因: {最弱维度及得分}
- 回溯目标: Phase {n}
- 本轮变更: {具体做了什么改变}
- 改进后评分: {新的八维度评分及综合分}
- 评分变化: {综合分从 X.X → Y.Y,变化 ±Z.Z}
目标:确认研究设计和数据之间的变量映射关系是否成立。
推荐方法:
check_variable_exists 验证)、定义是否清晰、是否需要转换或构造、是否有测量或缺失问题输出格式: A. Variable Mapping Confirmation(Outcome、Key explanatory variable、Main controls、Fixed effects candidates、Cluster candidates、Variables needing construction、Mapping issues to resolve)
落盘(必须)
目标:确认完整数据是否支持当前 baseline design。
推荐方法:基于 get_dataset_columns + scan_column(mode="full") 核对数据结构,scan_column(mode="sample") 核对关键变量分布与缺失率,检查:
若数据不能支持当前设计:明确指出原因、提出最小必要调整、暂不进入模型锁定
输出格式: B. Data Support Check(数据结构、可用样本量、时间覆盖、关键变量变化、缺失值担忧、异常值担忧、支持程度: Supported/Partially/Not supported、若不完全支持则给出最小调整方案)
落盘(必须)
目标:在变量映射和数据支持性都基本成立后,锁定主模型。
推荐方法:
输出格式: C. Baseline Plan Memo
**落盘(必须、不可跳过)**写入完整 baseline memo。
这一步是 Executor 的唯一输入文件,Executor 会读取;如果你不写这个文件,整个后续流水线直接停摆。即使当前数据只 "partially supported"、即使你还拿不定主意,也必须写一份 draft 版本并在文件头部标注:
---
status: draft | locked | partial
open_questions: [...]
---
目标:补充支持决策所需的最小描述性统计信息。注意:只提供支持决策的最小 descriptives,不要输出过多图表。
推荐方法:
输出格式: D. Descriptive Snapshot(描述性统计表、Helpful visuals、What the descriptives suggest 不超过5句) E. User Confirmation(Proceed to Run Baseline / Revise Variable Mapping / Revise Baseline Design / Need More Data)
在给出最终摘要之前,核对以下 8 个文件是否都已生成:
planner/stage_1_alignment.mdplanner/stage_2_literature.mdplanner/stage_3_hypothesis.mdplanner/stage_4_quality_gate.mdplanner/stage_5_variable_mapping.mdplanner/stage_6_data_support.mdplanner/stage_7_baseline_design.md ← 最关键planner/stage_8_descriptive_snapshot.md任何一个缺失 → 立刻补写再输出最终摘要。如果确实某 Phase 被合理跳过,也要写占位文件,文件内容说明跳过原因 + status: skipped。
完成核对后,提供一份完整的研究计划摘要(不超过5000字),涵盖:研究问题、假设、识别策略、基准方程、变量列表、稳健性检验计划。
目的:Planner 的产出直接决定 Executor 会跑什么回归、Reviewer 会审什么方案。摘要落盘不等于用户认可——必须在这里暂停,让用户亲自确认或提出修改,再由上层编排器进入下一 skill。
stage_*.md,其他已通过的 Phase 不重跑;修改完成后再次回到 Phase 9等待确认。stage_*.md 按需覆盖。status 从 draft / partial 改为 locked。---
**Planner 阶段已完成,等待你的确认**
- [A] 确认方案 → 进入 paper-reviewer 评审
- [B] 局部修改 → 指出想改的 Phase 和修改方向,我只回炉对应 Phase
- [C] 整体重做 → 从 Phase 1 重新规划
请选择 A / B / C,或直接说出你的修改意见。
这段必须原样出现,不得精简、翻译成英文、或换成隐含表述。