research

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文档查阅 执行步骤:

1. 使用 WebSearch 工具搜索相关信息
2. 使用 WebFetch 获取具体页面内容
3. 整理为结构化调研摘要(来源 + 结论 + 可信度)
4. 通过context创建research-note文档记录调研结果
5. 标注来源URL和可信度评级

指令2: 用户访谈 (user-interview)

触发场景: 需求模糊/缺失/存在多个合理选项 工具: AskUserQuestion (主线程 / 内联承载的角色可直接使用；派发子代理为非交互执行体，须经指令2b 以 needs_input 回传由 orchestrator 代问) 执行步骤:

1. 组织问题: 一次最多 MAX_QUESTIONS_PER_BATCH 个问题，每问题最多4个选项
2. 每个选项包含简短说明帮助决策
3. 通过AskUserQuestion向用户展示并等待回答
4. 收集完信息后写入当前文档相关章节
5. 不猜测，收集完再继续

指令2b 切换条件: 派发子代理执行（无交互通道，为常规路径），或主线程 AskUserQuestion 调用返回错误（工具不可用、权限被拒等运行时错误）。用户回答"其他"或回答不完整不触发切换，应追问澄清。

指令2b: 用户访谈 — deferred (user-interview-deferred)

触发条件: 派发子代理执行（无交互通道）或 AskUserQuestion 调用失败 / 工具不可用 步骤:

1. 保存已完成工作到正式文档路径（status=draft）
2. 以 <agent-result> 格式返回 needs_input 状态 + 问题列表 + 中间产出路径
3. orchestrator 通过 Interrupt-Resume Protocol 代为提问后以 continuation 模式恢复

指令3: 资料查阅 (doc-lookup)

触发场景: 需要参考已有项目文档/技术规范 执行步骤:

1. 通过 context navigate 分支（cataforge context read）按章节加载相关内容
2. 提取并汇总相关信息
3. 将摘要返回给调用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