Skein Research

skein-research — planning 调研方法论

🔒 本 skill 是 skein-researcher agent 的调研纪律单一真值源; agent .md 只留入参/回传/边界。 全局流程规则 (状态机/调度/优先级) 以 skein-flow/references/ 为单一真值源。

planning 阶段 main 派 agent 搜集信息 (库选型/方案对比/代码勘察/API 文档/第三方平台检索), 回传压缩结论 + 把全量调研落盘 research/。agent 自己负责数据源路由: 先本地代码/环境/API 文档勘察, 再发现并加载用户已有 research 类 skills, 最后按需做外部平台检索补证。

工作流五步 (normal 模式)

1. 本地勘察

Grep / Glob / Read 定位既有实现、约定、约束、依赖版本、本地 API 文档

• 带来源 (file:line); 无来源前缀 推测:。
• 环境事实优先来自仓内配置 / lockfile / README / docs / OpenAPI / SDK 文档; 需要命令探测时只跑只读 Bash。

2. 加载用户已有 research skills (如有)

find ~/.claude/skills ~/.trae-cn/skills .claude/skills .trae/skills -maxdepth 3 -iname 'SKILL.md' 2>/dev/null

• 只读取名称 / description / 适用边界; 命中 deep research / web research / social research / code research / policy research / market research 等与 query 相关的 skill 时, 采用其调研框架和检查清单增强本次调研。
• 不把已存在 skill 当事实源; 它只提供方法论。事实仍必须来自本地文件、官方文档、平台页面、搜索结果或明确标 推测:。
• 未发现合适 skill 时继续执行, 回传不需要额外标错。

3. 外部检索 (本地不足时)

WebSearch / WebFetch 取官方文档、库选型、方案对比、社区实践、GitHub、小红书等第三方平台信息

• 每条带 URL; 区分「文档写的」vs「社区说的」vs「推断的」。检索失败 → [工具失败: 检索 <query> 失败], 报已得素材。
• 外部平台按意图分层组合, 非全跑: 官方/API 文档优先 WebFetch 精读; GitHub 用于仓库实现 / issue / PR / stars 活跃度; 小红书/Twitter/Reddit/V2EX/B站用于真实用户场景和社区反馈。无登录态或平台不可达时声明覆盖缺口, 禁假装全网覆盖。
• 如果本地存在 agent-reach 之类第三方平台检索器, 可先只读探测 command -v agent-reach; 存在则按它自己的文档路由, 不重抄命令或自造抓取方案。不可用时降级 WebSearch/WebFetch 并声明限制。

4. 结论落盘 (MUST 做, 边研边增量双写)

经 Bash 落盘 (唯一写盘处), 每完成一主题即同步写, 非最后一次性; 这两文件只在真调研时产出 (main 未派你 = 不生, 不预建空壳):

mkdir -p .skein/task/<task-id>/research
# ① 过程证据 → research/<sid>.md = 当前 subtask 的完整结论 + 全部证据 + 权衡
# ② 收敛结论 → 追加进 .skein/task/<task-id>/findings.md (增量, 每主题一段: 结论 + 关键依据/引用 + 未决项)

• findings.md 由 agent 边研边增量写 (每主题收敛即追加, 首次写补 # <task> — 调研收敛 标题), 使后续 planning 整理只读 findings.md 不重读 research/。research/ = 过程证据留档, findings.md = 收敛交付。

5. 回传压缩结论 + research 任务收尾

按 agent 定义的返回 JSON 格式填: 收敛结论 (已增量写入 findings.md) + findings.md 路径 + subtask 收尾状态 + 需要 + 工具失败。

报告落盘后必须完成 research 任务状态收尾 (research 条目存 task.json 的 research_tasks[], 不在 subtasks[], 走 subtask done/fail 必报「subtask 不存在」):

skein research done <tid> <sid>

调研失败或缺少关键资料 → skein research fail <tid> <sid> --note "<原因>"。

入参 sid 为 null (未 claim 派发, 如 main 手派调研) 时跳过收尾自跑, 由 main 收。

bootstrap 模式 (入参 mode 为 bootstrap)

替换步骤 1-4 (本地勘察 / 加载 research skills / 外部检索 / 落盘) 为下述扫库动作; 步骤 5 回传照跑不变。无外部检索 (只读本仓代码), 落盘路径也另有专属值, 见末条。

扫代码库提炼既有约定为候选规则:

• 扫五维 (命名 / 错误处理 / 测试 / 架构边界 / 构建), 只提既有约定 (≥2 处一致证据), 命令式化描述, 产 rules namespace 候选。
• 第六项 product overview (与前五维性质不同): 额外扫一遍 README / docs/ / 顶层入口文件, 提炼当前系统是什么 (产品定位/核心功能域/主要用户流程), 产 1 篇 product namespace 现状快照候选 (非规则, 不要求 ≥2 处一致证据); 无 README/docs 可提炼 → 该项留空, 不用硬猜填充。
• 落盘 .skein/task/bootstrap/research/conventions.md; 层判定/取舍归 main+用户。

检查点

🛑 不碰项目代码 — 无 Write/Edit; 唯一写盘是 research/ 目录 (经 Bash)。 🛑 结论必落盘 (边研边增量) — 每主题即时写 research/.md (过程) + 追加 findings.md (收敛), 非最后一次性; 只回传不落盘 = 素材丢失且逼后续重读 research/。两文件仅真调研时产出。 🛑 先本地后外部 — 代码/环境/API 文档是本仓真值; 外部结论必须回扣本仓版本和约定。 🛑 用户 research skills 只增强方法论 — 可以加载其框架, 但不能把 skill 文案当事实证据。 🛑 带来源, 无来源标 推测: — file:line / URL; 区分文档/社区/推断。 🛑 不替用户拍板 — 给收敛结论 + 权衡, 选型决策交 main+用户。 🛑 缺信息标 需要: <问题> 回传, 由 main 转达用户 — 无 AskUserQuestion 权限。 🛑 工具失败必标 [工具失败: <原因>] — 检索/Fetch 失败时, 只标 [工具失败: <原因>], 空结果不当成功结果返回 (main 误判无信息)。 🛑 允许自跑 research done/fail；其余生命周期命令归 main — agent 是 research 任务状态唯一收尾者，main 只校验状态。

失败模式 (if-then 三段式)