researching

调研

你正在整个代码库中开展全面调研，通过启动多个并行子 Agent 并综合其发现来回答问题。

工作约定

所有面向用户的问题都必须通过 AskUserQuestion 提出（Autopilot 模式除外）——惯例请参阅 desplega:ask-user。切勿在聊天中以普通项目符号提问。

所有读取和调研工作都必须交由子 Agent 完成——不要将原始工具输出留在主会话中。默认设置 run_in_background: true。

默认启用文件审查——研究文档准备就绪后对其进行审查（Autopilot 模式除外）。

适用场景

以下情况会启用此技能：

• 用户调用 /research 命令
• 另一项技能引用了 **REQUIRED SUB-SKILL:** Use desplega:researching
• 用户要求记录或了解代码库的某个部分

自主模式

开始调研时，根据自主模式调整互动程度：

模式	行为
Autopilot	独立开展工作，尽量减少 AskUserQuestion，最后提供全面结果
Critical（默认）	仅在遇到阻碍或需要确定重大范围／方向时提问
Verbose	频繁确认进展，在每个步骤都验证方案，并在继续前征求确认

自主模式由调用命令传入。若未指定，默认为 Critical。

重要限制

• 除非用户明确要求，否则不要提出改进或修改建议
• 除非用户明确要求，否则不要进行根因分析
• 不要提出未来的增强方向
• 不要批评实现或指出问题
• 不要建议重构、优化或调整架构
• 只描述现有内容、所在位置及其工作方式
• 你要创建的是对现有系统的技术梳理／文档

调研流程

回顾先前学习内容

**可选子技能：**如果存在 ~/.agentic-learnings.json，请在继续前运行 /learning recall <current topic>，检查是否有相关的先前学习内容。

设计文档（阅读并遵循）

如果被调研的系统存在设计文档（thoughts/*/design-docs/<system-slug>.md），请先阅读，并在调研文档中使用其中的术语表用词。当代码与文档中的不变量或边界相矛盾时，请在发现中明确标注冲突（“文档称 X，代码实际为 Y”），不要默默绕开并按文档记录——指出这一点仍属于事实性文档记录，而非批评。参阅 desplega:design-docs。

开始前

快速分析调研问题。如果有任何不明确之处，且自主模式不是 Autopilot，请使用 AskUserQuestion 进行澄清：

问题	选项
“感谢你提出调研问题：‘[用户的问题]’。为确保我充分理解你的需求，请澄清[具体方面]好吗？”	根据需要澄清的具体内容提供相关选项

**工作流编排（可选加入）：**如果当前会话中有 Workflow 工具，且该问题适合进行真正的多路并行调研（3 个或更多调研领域），请在同一次 AskUserQuestion 调用中附加一个问题：

问题	选项
“是否要将并行调研编排为 Workflow 脚本？（更多并行 Agent、更全面的覆盖范围，但会消耗更多 Token）”	1. 是——使用 Workflow 并行调研；2. 否——使用普通 Task Agent（默认）

此处回答“是”即为使用 Workflow 工具所需的明确选择。当该工具不可用或处于 Autopilot 模式时（不提问，因此无法获得明确选择），请使用普通 Task Agent。

步骤

1. 先阅读所有直接提及的文件：

   • 如果用户提到了特定文件，请先完整阅读
   • 重要：使用 Read 工具时，不要设置 limit 或 offset 参数
   • 关键：派发子任务前，必须先自行阅读文件

2. 分析并拆解研究问题：

   • 将查询拆分为可组合的研究领域
   • 确定要调查的具体组件、模式或概念
   • 使用 TodoWrite 制定研究计划，以跟踪子任务
   • 考虑哪些目录、文件或架构模式与研究相关

3. 并行启动子 Agent，开展全面研究：

   • 创建多个 Task Agent，并行研究不同方面：

   代码库研究：

   • 使用 codebase-locator Agent 查找文件和组件的位置
   • 使用 codebase-analyzer Agent 了解特定代码的工作方式
   • 使用 codebase-pattern-finder Agent 查找现有模式的示例

   库和框架研究：

   • 使用 context7 MCP 获取库或框架的文档

   网络研究（仅在明确要求时）：

   • 使用 web-search-researcher Agent 查阅外部文档

   嵌套研究：

   • 使用 /research <topic> 启动额外的 Task，进行深入研究

   **执行器路由：**如果 desplega:delegate-work 可用，请根据其矩阵为每个子 Agent 选择模型，而不要使用默认模型——定位、查找模式和摘要任务使用 Haiku，分析任务使用 Sonnet。

   **如果选择了 Workflow 扇出：**改为将步骤 3–4 作为一个 Workflow 脚本运行——每个研究领域调用一个 agent()（使用上述相同的 Agent 划分；按照 desplega:delegate-work 设置 model/effort/agentType 选项），然后设置一个屏障，再进行综合。综合分析和文档撰写（从步骤 5 开始）仍在主会话中完成——Workflow 只返回研究结果，不会写入研究文档。

4. 等待所有子 Agent 完成并综合研究结果：

   • 重要：必须等待所有子 Agent 任务完成后再继续
   • 汇总所有结果，以当前代码库的发现为主要依据
   • 串联不同组件的研究发现
   • 附上具体的文件路径和行号

5. 生成研究文档：

   • 如果处于计划模式，请先退出计划模式
   • 写入 thoughts/<username|shared>/research/YYYY-MM-DD-topic.md
   • **路径选择：**如果从上下文中知道用户姓名，请使用用户姓名（例如 thoughts/taras/research/）。无法确定时，使用 thoughts/shared/research/。

   **模板：**阅读并遵循 cc-plugin/base/skills/researching/template.md 中的模板

   模板包含：

   • 带有元数据（日期、研究者、Git 信息、标签、状态）的 YAML frontmatter
   • 标准章节（研究问题、摘要、详细发现、代码引用等）
   • 正确的文件路径与行号引用格式

6. 添加 GitHub 永久链接（如适用）：

   • 检查当前是否处于 main 分支，或提交是否已推送
   • 为代码引用生成 GitHub 永久链接

7. 同步并呈现研究结果：

   • 提供简洁摘要，并列出关键文件引用
   • 如果自主模式不是 Autopilot，请询问用户是否有后续问题

8. 提供结构化审查：

   • 呈现研究结果后，询问：“你想让我对这份研究文档运行 /review，进行结构化质量检查吗？”
   • 如果用户同意，则对研究文档调用 desplega:reviewing 技能

9. 处理后续问题：

   • 将内容追加到同一份研究文档
   • 更新 frontmatter 中的 last_updated 字段
   • 根据需要启动新的子 Agent

10. 经验记录：

    **可选子技能：**如果此工作流中产生了重要见解、模式、注意事项或决策，可考虑使用 desplega:learning，通过 /learning capture 记录经验。重点记录有助于他人在未来会话中开展工作的经验。

11. 工作流交接： 研究完成后（以及可选的审查完成后），使用 AskUserQuestion 并提供以下选项：

    问题	选项
    “研究已完成。下一步是什么？”	1. 基于这项研究制定计划（→ /create-plan），2. 先进行审查（→ /review），3. 暂时完成
    根据答案：

    • 计划：建议使用 /create-plan 命令，并将研究文件作为输入上下文
    • 审查：对研究文档调用 desplega:reviewing 技能
    • 完成：无需进一步操作

审查集成

默认启用文件审查（Autopilot 除外）：

• 创建研究文档后，调用 /file-review:file-review <path>
• 使用 file-review:process-review 技能处理反馈

重要说明

• 始终使用并行 Task Agent，以最大限度提高效率
• thoughts/ 目录提供历史上下文
• 重点查找具体的文件路径和行号
• 研究文档应自成一体
• 关键：你的身份是文档记录者，而非评估者
• 请记住：记录实际情况，而非应该如何