specops 0.2.5 → 0.3.2

package/.opencode/workflows/diagnose-issues.md

@@ -0,0 +1,219 @@
+<purpose>
+编排并行调试 Agent 来调查 UAT 缺口并找到根因。
+
+UAT 发现缺口后，为每个缺口生成一个调试 Agent。每个 Agent 使用 UAT 预填的症状进行自主调查。收集根因，更新 UAT.md 缺口的诊断信息，然后交接给 plan-phase --gaps 处理实际诊断结果。
+
+编排器保持精简：解析缺口、生成 Agent、收集结果、更新 UAT。
+</purpose>
+
+<paths>
+DEBUG_DIR=.planning/debug
+
+调试文件使用 `.planning/debug/` 路径（带前导点的隐藏目录）。
+</paths>
+
+<core_principle>
+**先诊断再规划修复。**
+
+UAT 告诉我们什么坏了（症状）。调试 Agent 找出为什么坏了（根因）。plan-phase --gaps 然后基于实际原因创建针对性修复，而不是猜测。
+
+没有诊断："评论不刷新" → 猜测修复 → 可能猜错
+有诊断："评论不刷新" → "useEffect 缺少依赖" → 精确修复
+</core_principle>
+
+<process>
+
+<step name="parse_gaps">
+**从 UAT.md 提取缺口：**
+
+读取"Gaps"部分（YAML 格式）：
+```yaml
+- truth: "Comment appears immediately after submission"
+  status: failed
+  reason: "User reported: works but doesn't show until I refresh the page"
+  severity: major
+  test: 2
+  artifacts: []
+  missing: []
+```
+
+对于每个缺口，同时读取"Tests"部分中对应的测试以获取完整上下文。
+
+构建缺口列表：
+```
+gaps = [
+  {truth: "Comment appears immediately...", severity: "major", test_num: 2, reason: "..."},
+  {truth: "Reply button positioned correctly...", severity: "minor", test_num: 5, reason: "..."},
+  ...
+]
+```
+</step>
+
+<step name="report_plan">
+**向用户报告诊断计划：**
+
+```
+## 正在诊断 {N} 个缺口
+
+生成并行调试 Agent 来调查根因：
+
+| 缺口（预期行为） | 严重程度 |
+|-------------------|----------|
+| 提交后评论立即显示 | 重大 |
+| 回复按钮位置正确 | 轻微 |
+| 删除操作移除评论 | 阻塞 |
+
+每个 Agent 将：
+1. 创建 DEBUG-{slug}.md 并预填症状
+2. 自主调查（阅读代码、形成假设、测试）
+3. 返回根因
+
+这将并行运行——所有缺口同时调查。
+```
+</step>
+
+<step name="spawn_agents">
+**并行生成调试 Agent：**
+
+对于每个缺口，填充 debug-subagent-prompt 模板并生成：
+
+```
+Task(
+  prompt=filled_debug_subagent_prompt + "\n\n<files_to_read>\n- {phase_dir}/{phase_num}-UAT.md\n- .planning/STATE.md\n</files_to_read>",
+  subagent_type="general-purpose",
+  description="Debug: {truth_short}"
+)
+```
+
+**所有 Agent 在单条消息中生成**（并行执行）。
+
+模板占位符：
+- `{truth}`：失败的预期行为
+- `{expected}`：来自 UAT 测试
+- `{actual}`：来自 reason 字段的用户原始描述
+- `{errors}`：UAT 中的任何错误消息（或"无报告"）
+- `{reproduction}`：UAT 中的"测试 {test_num}"
+- `{timeline}`："在 UAT 期间发现"
+- `{goal}`：`find_root_cause_only`（UAT 流程——plan-phase --gaps 处理修复）
+- `{slug}`：从 truth 生成
+</step>
+
+<step name="collect_results">
+**从 Agent 收集根因：**
+
+每个 Agent 返回：
+```
+## 已找到根因
+
+**调试会话：** ${DEBUG_DIR}/{slug}.md
+
+**根因：** {具体原因及证据}
+
+**证据摘要：**
+- {关键发现 1}
+- {关键发现 2}
+- {关键发现 3}
+
+**涉及文件：**
+- {file1}：{问题所在}
+- {file2}：{相关问题}
+
+**建议修复方向：** {给 plan-phase --gaps 的简要提示}
+```
+
+解析每个返回以提取：
+- root_cause：诊断出的原因
+- files：涉及的文件
+- debug_path：调试会话文件路径
+- suggested_fix：缺口修复计划的提示
+
+如果 Agent 返回 `## 调查无定论`：
+- root_cause："调查无定论——需要人工审查"
+- 记录哪个问题需要人工关注
+- 包含 Agent 返回的剩余可能性
+</step>
+
+<step name="update_uat">
+**用诊断信息更新 UAT.md 缺口：**
+
+对于 Gaps 部分中的每个缺口，添加 artifacts 和 missing 字段：
+
+```yaml
+- truth: "Comment appears immediately after submission"
+  status: failed
+  reason: "User reported: works but doesn't show until I refresh the page"
+  severity: major
+  test: 2
+  root_cause: "useEffect in CommentList.tsx missing commentCount dependency"
+  artifacts:
+    - path: "src/components/CommentList.tsx"
+      issue: "useEffect missing dependency"
+  missing:
+    - "Add commentCount to useEffect dependency array"
+    - "Trigger re-render when new comment added"
+  debug_session: .planning/debug/comment-not-refreshing.md
+```
+
+将 frontmatter 中的状态更新为"diagnosed"。
+
+提交更新后的 UAT.md：
+```bash
+node .opencode/bin/specops-tools.cjs commit "docs({phase_num}): add root causes from diagnosis" --files ".planning/phases/XX-name/{phase_num}-UAT.md"
+```
+</step>
+
+<step name="report_results">
+**报告诊断结果并交接：**
+
+显示：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 诊断完成
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+| 缺口（预期行为） | 根因 | 文件 |
+|-------------------|------|------|
+| 提交后评论立即显示 | useEffect 缺少依赖 | CommentList.tsx |
+| 回复按钮位置正确 | CSS flex 顺序错误 | ReplyButton.tsx |
+| 删除操作移除评论 | API 缺少 auth header | api/comments.ts |
+
+调试会话：${DEBUG_DIR}/
+
+正在继续规划修复……
+```
+
+返回 verify-work 编排器进行自动规划。
+不要提供手动后续步骤——verify-work 处理后续流程。
+</step>
+
+</process>
+
+<context_efficiency>
+Agent 启动时已从 UAT 预填症状（无需症状收集）。
+Agent 只负责诊断——plan-phase --gaps 处理修复（不应用修复）。
+</context_efficiency>
+
+<failure_handling>
+**Agent 未能找到根因：**
+- 将缺口标记为"需要人工审查"
+- 继续处理其他缺口
+- 报告不完整的诊断
+
+**Agent 超时：**
+- 检查 DEBUG-{slug}.md 中的部分进展
+- 可以使用 /specops:debug 恢复
+
+**所有 Agent 都失败：**
+- 可能是系统性问题（权限、git 等）
+- 报告以供人工调查
+- 回退到不带根因的 plan-phase --gaps（精确度较低）
+</failure_handling>
+
+<success_criteria>
+- [ ] 已从 UAT.md 解析缺口
+- [ ] 已并行生成调试 Agent
+- [ ] 已从所有 Agent 收集根因
+- [ ] 已用 artifacts 和 missing 更新 UAT.md 缺口
+- [ ] 调试会话已保存到 ${DEBUG_DIR}/
+- [ ] 已交接给 verify-work 进行自动规划
+</success_criteria>

package/.opencode/workflows/discovery-phase.md

@@ -0,0 +1,288 @@
+<purpose>
+在适当的深度级别执行发现。
+生成 DISCOVERY.md（用于第 2-3 级），为 PLAN.md 的创建提供信息。
+
+由 plan-phase.md 的 mandatory_discovery 步骤调用，带有深度参数。
+
+注意：如需全面的生态系统研究（"专家如何构建这个"），请改用 /specops:research-phase，它会生成 RESEARCH.md。
+</purpose>
+
+<depth_levels>
+**此工作流支持三个深度级别：**
+
+| 级别 | 名称         | 时间      | 输出                                       | 适用场景                                  |
+| ---- | ------------ | --------- | ------------------------------------------ | ----------------------------------------- |
+| 1    | 快速验证     | 2-5 分钟  | 无文件，以验证后的知识继续                   | 单个库，确认当前语法                       |
+| 2    | 标准         | 15-30 分钟| DISCOVERY.md                               | 在选项间选择，新的外部集成                 |
+| 3    | 深度探索     | 1+ 小时   | 带验证门控的详细 DISCOVERY.md               | 架构决策，新颖问题                         |
+
+**深度由 plan-phase.md 在路由到此处之前确定。**
+</depth_levels>
+
+<source_hierarchy>
+**强制要求：Context7 优先于 WebSearch**
+
+Claude 的训练数据有 6-18 个月的滞后。始终进行验证。
+
+1. **Context7 MCP 优先** - 当前文档，无幻觉
+2. **官方文档** - 当 Context7 覆盖不足时
+3. **WebSearch 最后** - 仅用于比较和趋势
+
+参见 .opencode/templates/discovery.md `<discovery_protocol>` 获取完整协议。
+</source_hierarchy>
+
+<process>
+
+<step name="determine_depth">
+检查从 plan-phase.md 传入的深度参数：
+- `depth=verify` → 第 1 级（快速验证）
+- `depth=standard` → 第 2 级（标准发现）
+- `depth=deep` → 第 3 级（深度探索）
+
+路由到下方对应的级别工作流。
+</step>
+
+<step name="level_1_quick_verify">
+**第 1 级：快速验证（2-5 分钟）**
+
+适用于：单个已知库，确认语法/版本仍然正确。
+
+**流程：**
+
+1. 在 Context7 中解析库：
+
+   ```
+   mcp__context7__resolve-library-id with libraryName: "[library]"
+   ```
+
+2. 获取相关文档：
+
+   ```
+   mcp__context7__get-library-docs with:
+   - context7CompatibleLibraryID: [from step 1]
+   - topic: [specific concern]
+   ```
+
+3. 验证：
+
+   - 当前版本符合预期
+   - API 语法未变
+   - 近期版本无破坏性变更
+
+4. **如果验证通过：** 返回 plan-phase.md 并附带确认。无需 DISCOVERY.md。
+
+5. **如果发现问题：** 升级到第 2 级。
+
+**输出：** 口头确认继续，或升级到第 2 级。
+</step>
+
+<step name="level_2_standard">
+**第 2 级：标准发现（15-30 分钟）**
+
+适用于：在选项间选择，新的外部集成。
+
+**流程：**
+
+1. **确定需要发现什么：**
+
+   - 有哪些选项？
+   - 关键比较标准是什么？
+   - 我们的具体用例是什么？
+
+2. **对每个选项使用 Context7：**
+
+   ```
+   For each library/framework:
+   - mcp__context7__resolve-library-id
+   - mcp__context7__get-library-docs (mode: "code" for API, "info" for concepts)
+   ```
+
+3. **官方文档** 补充 Context7 缺失的内容。
+
+4. **WebSearch** 用于比较：
+
+   - "[option A] vs [option B] {current_year}"
+   - "[option] known issues"
+   - "[option] with [our stack]"
+
+5. **交叉验证：** 任何 WebSearch 发现 → 用 Context7/官方文档确认。
+
+6. **创建 DISCOVERY.md** 使用 .opencode/templates/discovery.md 结构：
+
+   - 带推荐的摘要
+   - 每个选项的关键发现
+   - 来自 Context7 的代码示例
+   - 置信度（第 2 级应为中高）
+
+7. 返回 plan-phase.md。
+
+**输出：** `.planning/phases/XX-name/DISCOVERY.md`
+</step>
+
+<step name="level_3_deep_dive">
+**第 3 级：深度探索（1+ 小时）**
+
+适用于：架构决策，新颖问题，高风险选择。
+
+**流程：**
+
+1. **界定发现范围** 使用 .opencode/templates/discovery.md：
+
+   - 定义清晰的范围
+   - 定义包含/排除边界
+   - 列出需要回答的具体问题
+
+2. **穷尽式 Context7 研究：**
+
+   - 所有相关库
+   - 相关模式和概念
+   - 如需要，每个库多个主题
+
+3. **深入阅读官方文档：**
+
+   - 架构指南
+   - 最佳实践章节
+   - 迁移/升级指南
+   - 已知限制
+
+4. **WebSearch 获取生态系统上下文：**
+
+   - 其他人如何解决类似问题
+   - 生产环境经验
+   - 陷阱和反模式
+   - 近期变更/公告
+
+5. **交叉验证所有发现：**
+
+   - 每个 WebSearch 声明 → 用权威来源验证
+   - 标记已验证 vs 假设
+   - 标记矛盾之处
+
+6. **创建全面的 DISCOVERY.md：**
+
+   - 来自 .opencode/templates/discovery.md 的完整结构
+   - 带来源归属的质量报告
+   - 按发现标注置信度
+   - 如果任何关键发现置信度为低 → 添加验证检查点
+
+7. **置信度门控：** 如果总体置信度为低，在继续之前展示选项。
+
+8. 返回 plan-phase.md。
+
+**输出：** `.planning/phases/XX-name/DISCOVERY.md`（全面版）
+</step>
+
+<step name="identify_unknowns">
+**用于第 2-3 级：** 定义我们需要学习什么。
+
+问：在规划此阶段之前，我们需要了解什么？
+
+- 技术选择？
+- 最佳实践？
+- API 模式？
+- 架构方案？
+</step>
+
+<step name="create_discovery_scope">
+使用 .opencode/templates/discovery.md。
+
+包含：
+
+- 清晰的发现目标
+- 有范围的包含/排除列表
+- 来源偏好（官方文档、Context7、当年）
+- DISCOVERY.md 的输出结构
+</step>
+
+<step name="execute_discovery">
+执行发现：
+- 使用 web search 获取当前信息
+- 使用 Context7 MCP 获取库文档
+- 优先使用当年来源
+- 按模板结构组织发现
+</step>
+
+<step name="create_discovery_output">
+写入 `.planning/phases/XX-name/DISCOVERY.md`：
+- 带推荐的摘要
+- 带来源的关键发现
+- 代码示例（如适用）
+- 元数据（置信度、依赖、开放问题、假设）
+</step>
+
+<step name="confidence_gate">
+创建 DISCOVERY.md 后，检查置信度。
+
+如果置信度为低：
+使用 AskUserQuestion：
+
+- header："低置信度"
+- question："发现置信度为低：[原因]。你希望如何继续？"
+- options：
+  - "深入研究" - 在规划前做更多研究
+  - "继续进行" - 接受不确定性，带注意事项规划
+  - "暂停" - 我需要考虑一下
+
+如果置信度为中：
+内联提示："发现完成（中等置信度）。[简要原因]。继续规划？"
+
+如果置信度为高：
+直接继续，仅注明："发现完成（高置信度）。"
+</step>
+
+<step name="open_questions_gate">
+如果 DISCOVERY.md 有 open_questions：
+
+内联展示：
+"发现中的开放问题：
+
+- [问题 1]
+- [问题 2]
+
+这些可能影响实现。确认并继续？（是 / 先处理）"
+
+如果选择"先处理"：收集用户对问题的输入，更新发现。
+</step>
+
+<step name="offer_next">
+```
+发现完成：.planning/phases/XX-name/DISCOVERY.md
+推荐：[一句话]
+置信度：[级别]
+
+接下来做什么？
+
+1. 讨论阶段上下文（/specops:discuss-phase [当前阶段]）
+2. 创建阶段计划（/specops:plan-phase [当前阶段]）
+3. 细化发现（深入研究）
+4. 审查发现
+```
+
+注意：DISCOVERY.md 不会单独提交。它将随阶段完成一起提交。
+</step>
+
+</process>
+
+<success_criteria>
+**第 1 级（快速验证）：**
+- 已咨询 Context7 获取库/主题信息
+- 当前状态已验证或问题已升级
+- 口头确认继续（无文件）
+
+**第 2 级（标准）：**
+- 已咨询 Context7 获取所有选项信息
+- WebSearch 发现已交叉验证
+- 已创建带推荐的 DISCOVERY.md
+- 置信度为中或更高
+- 已准备好为 PLAN.md 创建提供信息
+
+**第 3 级（深度探索）：**
+- 已定义发现范围
+- 已穷尽式咨询 Context7
+- 所有 WebSearch 发现已对照权威来源验证
+- 已创建全面分析的 DISCOVERY.md
+- 带来源归属的质量报告
+- 如果有低置信度发现 → 已定义验证检查点
+- 已通过置信度门控
+- 已准备好为 PLAN.md 创建提供信息
+</success_criteria>