first commit

sn-research-planning/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: sn-research-planning
+description: "[sn-deep-research 子阶段] 基于 request.md 生成研究计划 plan.json：定界、维度拆解、搜索策略、执行顺序。通常由 sn-deep-research 自动调用，不需手动触发。单独使用：用户已有研究主题，只需要规划不需要执行。"
+---
+
+# Research Planning
+
+产出 `plan.json`。它同时承担定界、报告形态约束和执行地图，用来指导 `sub_reports/*.md` 和最终 `report.md` 的生成；不是研究结论预设。
+
+## 行为边界
+
+做：
+
+- 从 `request.md` 识别研究目标、边界、受众、用途、时间/地域和假设。
+- 在需要时先做报告格式发现，再设计有依据的报告形态。
+- 设计轻量报告形态：终稿章节、结构依据、必须产出的表格/图/比较项、写作约束。
+- 把关键问题拆成可执行研究维度。
+- 让每个维度都能独立落盘为一个子报告。
+- 明确每个维度要回答什么、用什么方法、产出什么材料。
+- 为每个维度指定搜索策略和充分性标准。
+- 排出合理执行顺序和真实依赖。
+
+不做：
+
+- 不写研究结论。
+- 不把终稿章节直接复制成研究维度。
+- 不做单独的 `briefing.md`、`blueprint.json` 或 `synthesis.md`。
+- 不做资料综述或事实展开。
+- 不制造不必要的并行/依赖复杂度。
+
+## 输入
+
+- `{report_dir}/request.md`
+
+## 规划流程
+
+1. **锁定目标**：从 `request.md` 提取最终报告要服务的判断。
+2. **界定范围**：写清对象、时间、地域、受众/用途、排除项和执行假设。
+3. **判断是否需要格式发现**：如果用户已明确给出报告结构，或报告类型非常标准且约束明显，可直接进入下一步；否则先做一次轻量格式发现。
+4. **发现报告格式**：必要时读取 `sn-report-format-discovery`，识别报告类型、可信结构来源、必备章节、强制元素和风格约束，再压缩进 `plan.json.report_shape`。
+5. **设定报告形态**：给出终稿章节建议、结构依据、必备元素、适合的表格/图和写作约束。
+6. **抽取问题**：把关键问题分成基础事实、机制/原因、比较、影响、风险、趋势或建议类问题。
+7. **设计维度**：按“可独立研究、可回答问题、可贡献终稿”的标准合并或拆分维度。
+8. **定义任务**：为每个维度写清 `key_questions`、`method`、`search_strategy`、`expected_output` 和 `depends_on`。
+9. **定义搜索充分性**：说明需要覆盖哪些来源类型、至少几轮检索、哪些关键问题必须交叉确认。
+10. **排序执行**：先做定义、事实、背景和口径类维度，再做比较、解释、影响、判断类维度。
+11. **写完成标准**：明确什么条件下可以从分维度研究进入终稿写作。
+
+## 报告格式发现
+
+规划阶段不要求每次都单独研究格式，但在下列情况应主动做一次格式发现：
+
+- 用户只说“做个研究报告”，没有给章节结构。
+- 报告类型强依赖领域规范，如政策、法律、监管、学术/医学综述、尽调、技术选型。
+- 目标读者或使用场景会显著影响结构，如对外汇报、投决支持、内部选型、监管沟通。
+- 你不确定终稿应该优先呈现结论、时间线、比较矩阵、风险清单还是方法说明。
+
+可以直接从 `request.md` 推断 `genre`、`domain`、`audience`、`region`；若这些信息不足以稳健决定结构，再读取 `sn-report-format-discovery`。
+
+发现格式时只需要回答 4 件事：
+
+1. 这份报告最接近哪一类报告。
+2. 这类报告通常必须有哪些章节。
+3. 哪些非章节元素必须在终稿中出现，如对比表、时间线、风险矩阵、方法说明。
+4. 这些结构判断的依据是什么；如果没有找到高可信依据，回退逻辑是什么。
+
+格式发现的结果要压缩进 `plan.json.report_shape`，用于约束后续维度设计；不要另写独立格式文件，除非调用方明确要求。
+
+## 维度设计准则
+
+一个好维度应同时满足：
+
+- 能独立产出 `sub_reports/{id}.md`。
+- 有 2-5 个具体 `key_questions`。
+- 与其他维度边界清楚，重叠可解释。
+- 对 `report.md` 有明确贡献。
+- 有明确搜索入口和停止条件。
+- 不预设结论，只定义要查明什么。
+
+普通研究控制在 3-5 个维度；复杂研究最多 8 个维度。维度过多时优先合并同类问题。
+
+## 输出
+
+写入 `{report_dir}/plan.json`：
+
+```json
+{
+  "research_goal": "一句话目标",
+  "scope": {
+    "objects": ["研究对象"],
+    "time_range": "时间范围",
+    "region": "地域范围",
+    "audience_or_use": "目标读者或用途",
+    "exclusions": ["明确不做什么"],
+    "assumptions": ["执行假设"]
+  },
+  "report_shape": {
+    "format_basis": [
+      {
+        "type": "standard_guideline | official_template | real_exemplar | domain_convention | fallback",
+        "name": "结构依据名称",
+        "credibility_reason": "为什么可信",
+        "what_extracted": "从中抽取了哪些结构约束"
+      }
+    ],
+    "sections": ["终稿建议章节"],
+    "mandatory_elements": ["必须产出的表格、图、清单或比较项"],
+    "style": "写作口径和语气约束"
+  },
+  "completion_criteria": ["完成标准"],
+  "change_notes": [],
+  "dimensions": [
+    {
+      "id": "d1",
+      "name": "维度名称",
+      "description": "研究范围和边界",
+      "key_questions": ["必须回答的问题"],
+      "method": "检索、比较、案例分析、数据梳理、时序还原等",
+      "search_strategy": {
+        "source_types": ["应覆盖的来源类型"],
+        "seed_queries": ["起始检索词或检索方向"],
+        "freshness_requirement": "是否需要最新信息及时间范围",
+        "sufficiency": ["判断搜索足够的条件"]
+      },
+      "expected_output": "该维度子报告应提供给终稿写作的材料",
+      "depends_on": [],
+      "status": "pending"
+    }
+  ],
+  "execution_order": ["d1", "d2"]
+}
+```
+
+## 字段要求
+
+- `research_goal`：一句话说明整个研究要服务什么判断。
+- `scope`：必须覆盖对象、时间、地域、受众/用途、排除项和当前假设；未知项显式写明。
+- `report_shape.format_basis`：说明报告结构依据来自哪里。若调用过 `sn-report-format-discovery`，至少保留 1 个依据；若未调用，也要写明是“用户指定结构”或“通用领域惯例”。
+- `report_shape.sections`：是终稿结构建议，不是研究维度。
+- `report_shape.mandatory_elements`：列出终稿必须支撑的比较表、时间线、风险清单、指标矩阵、流程图等。
+- `report_shape.style`：说明报告语气、确定性表达和不确定性处理方式。
+- `completion_criteria`：列出进入终稿写作前必须满足的条件。
+- `change_notes`：初始为空数组；研究过程中如调整维度或执行顺序，把原因追加到这里，不单独写日志文件。
+- `id`：使用稳定短 ID，如 `d1`、`d2`。
+- `description`：说明研究范围和不包含什么。
+- `key_questions`：写成可回答的问题，不写成标题。
+- `method`：说明该维度适合怎么研究。
+- `search_strategy.source_types`：列出要覆盖的来源类型，如官方文件、监管公告、学术论文、行业报告、公司披露、产品文档、新闻报道、社区讨论等。
+- `search_strategy.seed_queries`：给出 3-6 个起始检索方向，而不是只写一个关键词。
+- `search_strategy.freshness_requirement`：说明是否必须查最新资料；涉及市场、政策、产品、公司、价格、法律、人物时必须要求最新核查。
+- `search_strategy.sufficiency`：写清停止条件，如“每个关键问题至少有材料支撑”“核心事实来自两个独立来源”“没有新信息增量后停止”等。
+- `expected_output`：说明子报告要贡献事实、比较、框架、判断依据、风险清单或场景分析中的哪一种。
+- `depends_on`：只写真实依赖；没有依赖则为空数组。
+- `execution_order`：必须覆盖所有维度 ID，且依赖项出现在被依赖项之前。
+
+## 完成标准示例
+
+- 所有 `key_questions` 至少被一个维度覆盖。
+- `report_shape` 有明确结构依据，而不是拍脑袋列章节。
+- `report_shape.mandatory_elements` 都有对应维度提供材料。
+- 每个维度都能形成独立子报告。
+- 每个维度都定义了搜索策略和停止条件。
+- 关键不确定性有专门维度处理，或在相关维度中明确标注。
+
+## 常见失败
+
+- 把报告章节当研究维度。
+- 每个维度只有标题，没有可回答问题。
+- 维度之间大量重叠。
+- 没有为维度定义搜索入口，导致执行时浅搜。
+- 执行顺序忽略依赖关系。
+- 报告结构没有依据，只凭经验硬写章节。
+- 忽略终稿必备元素。
+- 在计划里提前写结论。