| name | research |
| description | 调查研究 — 网络检索 (web-search)、用户访谈 (user-interview)、资料查阅 (doc-lookup)，解决不确定性。当 agent 遇到信息缺失 / 用户输入模糊 / 技术选型需对比 / 不确定不应猜测时使用此 skill。本 skill 仅产出调研记录与选项，不替 agent 做决策（由调用方决策），不生成正式文档（由 context 负责）。 |
| argument-hint | <调研模式: web-search|user-interview|doc-lookup> <问题描述> |
| suggested-tools | file_read, file_glob, file_grep, web_search, web_fetch, user_question |
| depends | ["context"] |
| disable-model-invocation | false |
| user-invocable | true |
调查研究 (research)
能力边界
- 能做: 网络检索(web-search)、用户访谈(user-interview)、资料查阅(doc-lookup)
- 不做: 替Agent做决策、生成文档内容、技术选型最终判定与推荐排序（由 tech-eval 负责）
调研决策树
Agent遇到不确定性时:
- 信息可从网络获取? → web-search
- 信息取决于用户偏好/业务决策? → user-interview (选择题优先)
- 信息在已有文档中? → doc-lookup (通过context加载)
- 以上均不适用? → 标注为[ASSUMPTION]并在文档中声明
操作指令
指令1: 网络检索 (web-search)
触发场景: 技术选型/最佳实践/竞品分析/API文档查阅
执行步骤:
- 使用 WebSearch 工具搜索相关信息
- 使用 WebFetch 获取具体页面内容
- 整理为结构化调研摘要(来源 + 结论 + 可信度)
- 通过context创建research-note文档记录调研结果
- 标注来源URL和可信度评级
指令2: 用户访谈 (user-interview)
触发场景: 需求模糊/缺失/存在多个合理选项
工具: AskUserQuestion (主线程 / 内联承载的角色可直接使用；派发子代理为非交互执行体，须经指令2b 以 needs_input 回传由 orchestrator 代问)
执行步骤:
- 组织问题: 一次最多 MAX_QUESTIONS_PER_BATCH 个问题，每问题最多4个选项
- 每个选项包含简短说明帮助决策
- 通过AskUserQuestion向用户展示并等待回答
- 收集完信息后写入当前文档相关章节
- 不猜测，收集完再继续
指令2b 切换条件: 派发子代理执行（无交互通道，为常规路径），或主线程 AskUserQuestion 调用返回错误（工具不可用、权限被拒等运行时错误）。用户回答"其他"或回答不完整不触发切换，应追问澄清。
指令2b: 用户访谈 — deferred (user-interview-deferred)
触发条件: 派发子代理执行（无交互通道）或 AskUserQuestion 调用失败 / 工具不可用
步骤:
- 保存已完成工作到正式文档路径（status=draft）
- 以
<agent-result> 格式返回 needs_input 状态 + 问题列表 + 中间产出路径
- orchestrator 通过 Interrupt-Resume Protocol 代为提问后以 continuation 模式恢复
指令3: 资料查阅 (doc-lookup)
触发场景: 需要参考已有项目文档/技术规范
执行步骤:
- 通过 context navigate 分支（
cataforge context read）按章节加载相关内容
- 提取并汇总相关信息
- 将摘要返回给调用Agent
Anti-Patterns
- 禁止: 用 web-search 替代已有 docs/research/ 已记录结论 — research-note 是去重的单一事实源，跳过会产生重复调研并污染上下文
- 禁止: 不写 research-note 就把调研结论作为下游决策依据 — evidence 链断裂后 reflector / sprint-review 无法追溯结论合理性
- 禁止: 把推测当 evidence 引用 — 未标 [ASSUMPTION] 的假设进入正式文档会让 reviewer 无法识别"已确认事实"和"待验证猜测"
- 避免: 一次 user-interview 提问超过 MAX_QUESTIONS_PER_BATCH — 用户决策成本陡升、回答完整度下降，应按 batch 拆分
- 禁止: web-search / web-fetch 不可达或被拒时静默返回空结论 —— 按 COMMON-RULES §通用 Error Handling 标 [ASSUMPTION] 给出基于已有上下文的合理默认并记录待验证缺口，仅在结论完全无法支撑时返回 blocked
