用途
该技能用于对代码库进行全面的“现状研究”，回答用户关于代码库的问题。其核心定位是：只记录和解释代码库当前实际存在的状态，不提出改进、不进行根因分析、不推荐重构或优化，除非用户明确要求。它产出的是一份关于现有系统的技术地图/文档。
主要能力
- 读取用户直接提到的文件（工单、文档、JSON 等），要求完整读取，不使用 limit/offset 参数。
- 将研究问题拆解为可组合的研究领域，识别需要调查的组件、模式或概念，并用 TodoWrite 创建研究计划。
- 并行启动多个子代理执行研究任务，包括：
- scout 代理：综合性的代码库探索（定位、分析、模式查找）。
- thoughts-locator 代理：发现关于该主题已存在的文档。
- thoughts-analyzer 代理：从最相关的具体文档中提取关键见解。
- web-search-researcher 代理：仅在用户明确要求时进行外部文档与资源检索，并要求返回链接。
- linear-ticket-reader 代理：获取特定 Linear 工单的完整细节。
- linear-searcher 代理：查找相关工单或历史背景。
- 等待所有子代理完成后综合结果：以实时代码库发现为主要事实来源，thoughts/ 发现作为补充历史背景，连接不同组件的发现，包含具体文件路径和行号。
- 收集元数据：运行 hack/spec_metadata.sh 脚本生成相关元数据。
- 生成研究文档，保存到 thoughts/shared/research/ 目录，文件名格式为 YYYY-MM-DD-ENG-XXXX-description.md（有工单号时包含 ENG-XXXX，无工单号则省略）。
- 文档结构包含 YAML frontmatter（date、researcher、git_commit、branch、repository、topic、tags、status、last_updated、last_updated_by）以及正文：研究问题、摘要、详细发现、代码引用、架构文档、历史背景（来自 thoughts/）、相关研究、待解决问题。
- 在适用时添加 GitHub 永久链接：检查是否在 main 分支或提交已推送，使用 gh repo view --json owner,name 获取仓库信息，生成 https://github.com/{owner}/{repo}/blob/{commit}/{file}#L{line} 形式的链接并替换本地文件引用。
- 处理后续问题：将后续研究追加到同一文档，更新 frontmatter 的 last_updated 和 last_updated_by，添加 last_updated_note，并新增“## Follow-up Research [timestamp]”章节。
使用方式
调用该命令后，它会先回复：“I'm ready to research the codebase. Please provide your research question or area of interest, and I'll analyze it thoroughly by exploring relevant components and connections.” 然后等待用户提供研究问题。收到问题后按以下步骤执行：
- 先完整读取用户直接提到的文件（在主上下文中自行读取，再拆解研究）。
- 分析并拆解研究问题，创建研究计划。
- 并行启动子代理任务进行综合研究。
- 等待所有子代理完成并综合发现。
- 收集研究文档的元数据。
- 生成研究文档（确保目录存在：mkdir -p thoughts/shared/research）。
- 添加 GitHub 永久链接（如适用）。
- 向用户呈现简明发现摘要，包含关键文件引用，并询问是否有后续问题。
- 处理后续问题，追加到同一文档并同步更新。
适用场景
- 需要理解现有代码库中某个主题、组件或架构模式的实际实现。
- 需要梳理跨组件的连接关系与系统交互方式。
- 需要结合 thoughts/ 目录中的历史背景来补充实时代码发现。
- 需要为开发者提供带具体文件路径和行号的可导航技术文档。
- 需要为后续工作建立自包含的研究文档，并可能附上 GitHub 永久链接。
限制与注意事项
- 只描述现状，不评价、不建议改进、不进行根因分析、不推荐重构或优化，除非用户明确要求。
- 所有代理都是记录者而非批评者。
- 必须始终使用并行 Task 代理，始终运行全新的代码库研究，不能仅依赖已有研究文档。
- 必须严格按编号步骤执行：先读取提到的文件，再启动子任务；等待所有子代理完成后再综合；先收集元数据再写文档；不得使用占位值写研究文档。
- 路径处理：thoughts/searchable/ 目录包含用于搜索的硬链接，记录路径时只移除“searchable/”，保留其他所有子目录，不得把 allison/ 改成 shared/ 或反之。
- frontmatter 需保持一致，多词字段名使用 snake_case，标签应与研究主题和组件相关。
- 外部网页研究仅在用户明确要求时进行，并要求返回链接。
- 关于收费、价格、平台支持等具体信息，资料中暂未提供。