ccg-ros2-workflow 2.2.1 → 3.0.0

package/templates/engine/strategies/debug-investigate.md

@@ -0,0 +1,169 @@
+# Strategy: Debug Investigate — 深度调试
+
+> 适用于原因不明的复杂 bug，需要多模型并行诊断和交叉验证。
+
+## 适用条件
+- 复杂度 M 或以上
+- 错误原因不明确
+- 需要多角度诊断
+
+## 前置加载
+
+```
+Read("~/.claude/.ccg/engine/model-router.md")
+```
+
+---
+
+## 工作流状态机
+
+[phase-state:1-collect]
+当前阶段：信息收集
+📍 Next: 收集完错误信息后启动双模型诊断
+[/phase-state:1-collect]
+
+[phase-state:2-diagnose]
+当前阶段：双模型并行诊断
+Gate: 错误信息已收集 ✓
+📍 Next: 双模型诊断返回后进入交叉验证
+[/phase-state:2-diagnose]
+
+[phase-state:3-validate]
+当前阶段：交叉验证
+Gate: 双模型诊断已返回 ✓
+📍 Next: 假设排序后请用户确认修复方向
+[/phase-state:3-validate]
+
+[phase-state:4-confirm]
+当前阶段：用户确认（HARD STOP）
+Gate: 假设已排序 ✓
+📍 Next: 用户确认后进入修复
+[/phase-state:4-confirm]
+
+[phase-state:5-fix]
+当前阶段：修复与验证
+Gate: 用户已确认修复方向 ✓
+📍 Next: 修复完成后报告结果
+[/phase-state:5-fix]
+
+---
+
+## 阶段详情
+
+### Phase 1: 信息收集 [required]
+
+**Task 更新**：`currentPhase → "1-collect"`, `nextAction → "收集错误信息"`
+
+1. 收集错误上下文：
+   - 错误消息 / 堆栈跟踪
+   - 复现步骤（如果有）
+   - 最近的相关变更（`git log --oneline -10`）
+   - 环境信息（如相关）
+
+2. 搜索相关代码（Grep/MCP）
+3. 读取可能相关的文件
+
+### Phase 2: 双模型并行诊断 [required]
+
+**Gate check**: 错误信息已收集
+
+**并行调用**（`run_in_background: true`）：
+- **backend 模型**：debugger 角色
+  ```
+  <TASK>
+  需求：诊断以下问题
+  上下文：[错误信息、堆栈、相关代码]
+  </TASK>
+  OUTPUT: 诊断假设（按可能性排序，每个假设含：根因分析、证据、修复建议）
+  ```
+- **frontend 模型**：debugger 角色（相同格式）
+
+等待双模型返回。
+
+**Task 更新**：`currentPhase → "2-diagnose"`, `nextAction → "等待双模型诊断返回"`
+
+### Phase 3: 交叉验证
+
+**Gate check**: 双模型诊断已返回
+
+1. 对比两个模型的诊断结果
+2. 找出共识点（两个模型都指出的问题 → 高可信度）
+3. 找出分歧点（只有一个模型指出 → 需要验证）
+4. 综合排序所有假设：
+
+```
+🔍 诊断结果
+
+### 高可信度假设（双模型共识）
+1. [假设] — [证据]
+   修复方案: [具体方案]
+
+### 待验证假设（单模型提出）
+2. [假设] — [来源模型] — [证据]
+   修复方案: [具体方案]
+
+### 已排除
+- [假设] — [排除理由]
+```
+
+### Phase 4: 用户确认 [required · HARD STOP]
+
+**Gate check**: 假设已排序
+
+展示诊断结果，请用户选择修复方向：
+- 按假设 1 修复
+- 按假设 2 修复
+- 需要更多调查
+- 其他方向
+
+**Task 更新**：
+```
+更新 task.json:
+  currentPhase → "4-confirm"
+  gate → "user_approval_required"
+  nextAction → "等待用户确认修复方向"
+```
+
+**必须等待用户明确确认**，不可自动选择。
+
+用户确认后：`task.json: gate → null, currentPhase → "5-fix"`
+
+### Phase 5: 修复与验证
+
+**Gate check**: 用户已确认
+
+1. 按确认的方向应用修复
+2. 运行测试验证
+3. 如果修复无效 → 回退，尝试下一个假设，或返回 Phase 4 重新确认
+4. 输出结果：
+   ```
+   ✅ 调试完成
+     根因: [确认的根因]
+     修复: [应用的修复]
+     验证: [测试结果]
+     📍 Next: /ccg commit 提交修复
+   ```
+
+#### Spec Evolution（归档前必须执行）
+
+参考 `phase-guide.md § 8 Spec Evolution Protocol` 执行：
+1. 分析本次调试的根因和修复方案，提炼可复用的调试经验和防御性编码约定
+2. 如有值得记录的经验（特别是非显而易见的坑）→ 草拟 Spec 条目，展示给用户确认后追加到 `.ccg/spec/{domain}/index.md`
+3. 无值得提炼的经验 → 跳过
+
+**Task 更新**：`status → "archived"`
+
+**归档任务**：
+```bash
+mkdir -p .ccg/tasks/archive/$(date +%Y-%m) && mv .ccg/tasks/{task-name} .ccg/tasks/archive/$(date +%Y-%m)/
+git add .ccg/tasks/ && git commit -m "chore: archive ccg task"
+```
+
+---
+
+## 铁律
+
+- **Phase 4 是 HARD STOP** — 不可自动决定修复方向
+- **双模型诊断必须并行** — 独立诊断才有交叉验证价值
+- **修复前必须有诊断** — 不可跳过 Phase 2-3 直接改代码
+- **修复无效时必须回退** — 不可在错误方向上继续深入

package/templates/engine/strategies/deep-research.md

@@ -0,0 +1,141 @@
+# Strategy: Deep Research — 深度研究
+
+> 适用于技术方案研究、对比分析。多模型并行探索，结构化输出。
+
+## 适用条件
+- 用户提出研究/分析/对比类问题
+- 不涉及代码修改（纯研究）
+- 任何复杂度级别
+
+## 前置加载
+
+```
+Read("~/.claude/.ccg/engine/model-router.md")
+```
+
+---
+
+## 工作流状态机
+
+[phase-state:1-clarify]
+当前阶段：明确研究问题
+📍 Next: 问题明确后启动多模型探索
+[/phase-state:1-clarify]
+
+[phase-state:2-explore]
+当前阶段：多模型并行探索
+Gate: 研究问题已明确 ✓
+📍 Next: 双模型结果返回后进入综合
+[/phase-state:2-explore]
+
+[phase-state:3-synthesize]
+当前阶段：综合分析
+Gate: 双模型探索已返回 ✓
+📍 Next: 输出结构化报告后进入讨论
+[/phase-state:3-synthesize]
+
+[phase-state:4-discuss]
+当前阶段：交互式讨论
+📍 Next: 用户满意后结束
+[/phase-state:4-discuss]
+
+---
+
+## 阶段详情
+
+### Phase 1: 明确问题 [required]
+
+1. 解析用户的研究意图：
+   - 要研究什么？
+   - 研究目的是什么？（做决策？了解现状？评估可行性？）
+   - 有什么约束或偏好？
+
+2. 如果问题太宽泛，先收窄：
+   ```
+   📋 研究范围
+     问题: [明确的研究问题]
+     目的: [决策/了解/评估]
+     约束: [时间/技术/资源约束]
+   ```
+
+### Phase 2: 多模型并行探索 [required]
+
+**Task 更新**：`currentPhase → "2-explore"`, `nextAction → "双模型并行探索"`
+
+**并行调用**（`run_in_background: true`）：
+- **backend 模型**：analyzer 角色
+  ```
+  <TASK>
+  需求：研究分析 [问题]
+  上下文：[项目上下文、技术栈、约束]
+  </TASK>
+  OUTPUT: 技术分析报告（可行性、架构选项、风险、成本估算）
+  ```
+- **frontend 模型**：analyzer 角色
+  ```
+  <TASK>
+  需求：研究分析 [问题]
+  上下文：[项目上下文、用户场景、约束]
+  </TASK>
+  OUTPUT: 用户/体验视角分析（UX 影响、用户流程、设计选项）
+  ```
+
+等待双模型返回。
+
+### Phase 3: 综合分析
+
+**Gate check**: 双模型探索已返回
+
+交叉对比双方视角。
+
+**持久化研究成果**（如有任务目录）：
+- 将双模型原始分析写入 `.ccg/tasks/{task-name}/research/backend-analysis.md`
+- 将双模型原始分析写入 `.ccg/tasks/{task-name}/research/frontend-analysis.md`
+
+输出结构化报告：
+
+```
+📋 研究报告: [主题]
+
+## 选项对比
+
+| 维度 | 方案 A | 方案 B | 方案 C |
+|------|--------|--------|--------|
+| 概述 | ... | ... | ... |
+| 优势 | ... | ... | ... |
+| 劣势 | ... | ... | ... |
+| 复杂度 | S/M/L | S/M/L | S/M/L |
+| 风险 | low/mid/high | ... | ... |
+| 预估工期 | ... | ... | ... |
+
+## 推荐
+
+**推荐方案 [X]**
+理由：[简明理由]
+
+## 注意事项
+- [关键风险或注意点]
+```
+
+### Phase 4: 交互式讨论
+
+用户可以：
+- 追问某个方案的细节
+- 要求更深入分析某个方面
+- 要求 POC / 原型验证
+- 确认结论并结束
+
+```
+📍 研究已完成。如需实施推荐方案，可以用 /ccg:go implement [方案描述]
+```
+
+**Task 更新**（如有）：`status → "completed"`, `nextAction → "研究完成，可实施推荐方案"`
+
+---
+
+## 铁律
+
+- **纯研究模式，不做代码修改** — 除非用户明确要求 POC
+- **结果必须结构化输出** — 表格对比，不是自由聊天
+- **必须给出推荐** — 不可只列选项不做判断
+- **双模型探索必须并行** — 独立视角更有价值

package/templates/engine/strategies/direct-fix.md

@@ -0,0 +1,108 @@
+# Strategy: Direct Fix — 直接修复
+
+> 适用于范围清晰、单文件的简单 bug 修复。Claude 独立完成，不调用外部模型。
+
+## 适用条件
+- 复杂度 S（单文件，<30 行变更）
+- 错误信息或复现路径明确
+- 风险 low 或 medium
+
+---
+
+## 工作流状态机
+
+[phase-state:1-locate]
+当前阶段：定位问题代码
+Gate: 项目上下文已获取 ✓（由 /ccg Phase 1 完成）
+📍 Next: 找到问题代码后进入诊断阶段
+[/phase-state:1-locate]
+
+[phase-state:2-diagnose]
+当前阶段：诊断根因
+Gate: 已找到相关代码 ✓
+📍 Next: 确定根因后进入修复阶段
+[/phase-state:2-diagnose]
+
+[phase-state:3-fix]
+当前阶段：应用修复
+Gate: 根因已确定 ✓
+📍 Next: 修复完成后进入验证阶段
+[/phase-state:3-fix]
+
+[phase-state:4-verify]
+当前阶段：验证修复
+Gate: 修复已应用 ✓
+📍 Next: 验证通过后报告结果，建议提交
+[/phase-state:4-verify]
+
+---
+
+## 阶段详情
+
+### Phase 1: 定位 [required]
+
+1. 从用户描述中提取关键信息：
+   - 错误消息（如果有）
+   - 发生位置（文件、功能、页面）
+   - 复现步骤
+
+2. 搜索相关代码：
+   - 有错误消息 → `Grep` 搜索错误文本
+   - 有文件/函数名 → 直接 `Read` 目标文件
+   - 信息不足 → 用 MCP 搜索工具或 `Grep` 按关键词搜索
+
+3. 读取找到的代码文件，理解上下文
+
+### Phase 2: 诊断 [required]
+
+1. 分析代码逻辑，找到 bug 的根因
+2. 如果有多个可能原因，按可能性排序
+3. 简要说明诊断结果：
+   ```
+   🔍 诊断
+     文件: [path:line]
+     根因: [一句话说明]
+     修复方案: [一句话说明]
+   ```
+
+### Phase 3: 修复
+
+1. 应用最小修复（只改必要的部分）
+2. 如果项目有测试 → 运行相关测试
+3. 如果没有测试 → 建议但不强制添加
+
+### Phase 4: 验证
+
+1. `git diff` 展示变更
+2. 确认修复合理性：
+   - 变更范围是否最小？
+   - 是否引入新问题？
+   - 边界条件是否考虑？
+3. 如果修复涉及认证/输入处理/安全相关代码 → `/verify-security` 安全扫描
+4. 输出结果：
+   ```
+   ✅ 修复完成
+     变更: [N] 文件，[M] 行
+     根因: [简述]
+     修复: [简述]
+     📍 Next: 可以用 /ccg:commit 提交
+   ```
+
+---
+
+## 升级规则
+
+如果在 Phase 1-2 中发现以下情况，建议升级：
+- 涉及 3+ 文件 → 升级到 `guided-develop`
+- 原因不明，需要深度调试 → 升级到 `debug-investigate`
+- 涉及架构问题 → 升级到 `refactor-safely`
+
+告知用户并等待确认后切换策略。
+
+---
+
+## 铁律
+
+- **不可在未读代码的情况下猜测修复方案** — Phase 1 必须实际读取代码
+- **最小修复原则** — 只改导致 bug 的部分，不做"顺手重构"
+- **不可跳过诊断直接改代码** — 即使"一眼看出问题"，也要经过 Phase 2 确认根因