Su Plan

---
name: su-plan
description: 按 CCB 主流程完成需求分析、多轮协商、技术设计、任务切片，并生成供派工使用的精简 spec。
metadata:
  short-description: SU 规划与协商
---

# SU 规划与协商

## 触发条件
- 用户提出新的实现需求、重构需求或勘探需求。
- 当前任务尚未形成可派工的 spec。
- 现有设计冲突，需要回到方案层重新整理。

## 输入
- 用户需求描述。
- 项目索引：`docs/.ccb/index/*.yaml` 与 `docs/.catalog.yaml`。
- 按需读取的需求、架构、计划文档。

## 执行流程

### Step 0：项目上下文就绪检查
0. 检查 `docs/.ccb/index/project.yaml` 是否存在。
   - 若不存在（空项目初始化后首次运行），自动扫描项目结构并生成。
   - 若存在，读取项目事实作为后续分析的基础。

### Step 1：需求分析
1. 判断任务复杂度是简单、中等还是复杂。
2. 明确是否需要输出需求文档；简单任务可直接进入 spec，复杂任务先写需求或设计文档。
3. **自动发起协商**：通过 `ask <provider> --foreground` 向 Codex 发起 `mode: consult` 协商请求，收集对代码现状的意见和可行性分析。
4. 等待用户确认需求（🔴 必审门）。

### Step 2：技术设计
5. 通过索引定位架构与模块信息。
6. **自动发起协商**：通过 `ask <provider> --foreground` 向 Codex 发起技术方案协商，收集实现可行性、技术最优解、风险评估。
7. 根据 Codex 回复中的 `analysis_depth_hint` 自动触发 SuperClaude 深度分析。
8. 进行方案对比、风险分析与关键决策说明。
9. 等待用户确认设计（🔴 必审门）。

### Step 3：任务切片
10. 判断模式是实施、半开放实施还是勘探。
11. 将任务拆成可验收切片，写出 20-50 行的精简 spec。
12. 生成面向 `su-dispatch` 的派工摘要。

## 多轮协商机制

### 协商触发时机
- Step 1 需求分析：当需求涉及代码现状理解、可行性判断时自动触发
- Step 2 技术设计：当需要方案对比、架构影响评估时自动触发

### 协商轮次控制
- `soft_max_rounds = 3`：大多数情况足够收敛
- `hard_max_rounds = 5`：架构权衡可能需要 4-5 轮
- Claude 把控轮次，不由 Codex 或用户控制

### 自动停止条件
Claude 在以下任一条件满足时终止协商：
- Codex 返回 `status=blocked`
- 所有决策关键问题已回答
- 连续两轮：`status=answered` + 无新 findings + 无新 open_questions + recommendation 稳定
- 达到 `hard_max_rounds`
- 剩余开放问题均为低影响可逆决策

### 到达上限后的行为
| 场景 | 动作 |
|------|------|
| 低风险、可逆、局部决策 | Claude 带假设冻结设计 |
| 高影响、跨模块、契约/模式/流程决策 | 升级给用户 |
| 上下文不足 | 升级给用户或要求更多源材料 |

### 协商产出归档
- **默认**：Claude 生成结构化摘要，嵌入 Step 1/2 设计文档
- **重大决策**：额外写入 ADR（`.ccb/decisions/`）
- 摘要包含：讨论主题、考虑的选项、Codex 建议、Claude 最终决策、理由、未解决风险

### 上下文传递规则
- 每轮传递滚动结构化摘要，不传完整历史
- `confirmed_conclusions`：上限 5-8 条
- `open_questions`：仅当前未解决项
- `delta_since_last_round`：round > 1 时必填

## SuperClaude 集成

### 必须触发
- 进入 Step 2 技术设计的协商前，触发 `/sc:design [目标摘要]`

### 条件触发（由 Codex 回复中的 analysis_depth_hint 驱动）
| Codex hint | SC 命令 | 触发规则 |
|------------|---------|---------|
| `sc-brainstorm` | `/sc:brainstorm` | Step 1，需求仍模糊/目标冲突/范围未拆解 |
| `sc-design` | `/sc:design` | 架构边界/模块拆分/接口设计需深度推理 |
| `sc-analyze` + security | `/sc:analyze --focus security` | 安全风险高影响且影响设计选择 |
| `sc-analyze` + performance | `/sc:analyze --focus performance` | 性能在关键路径 |
| `sc-spec-panel` | `/sc:spec-panel` | ≥2 个可行设计 + 权衡高影响或跨模块 |
| `sc-estimate` | `/sc:estimate` | 需要规模估算来决定拆分/顺序/资源 |
| `sc-troubleshoot` | `/sc:troubleshoot` | 协商主题是故障诊断 |
| `sc-research` | `/sc:research` | 缺失信息是仓库和文档之外的外部信息 |
| `human-decision` | **不触发 SC** | 升级给用户，SC 不替代用户权威 |

### 建议触发
- 方案需多专家审查时：`/sc:spec-panel [spec 路径]`
- 任务复杂需结构化工作流时：`/sc:workflow [PRD 路径]`
- 需要工作量评估时：`/sc:estimate [任务描述]`

## 输出格式
- 需求理解摘要。
- 协商结论摘要（如有协商轮次）。
- 技术方案摘要。
- 任务模式与切片说明。
- 精简 spec 路径或草案正文。

## 停止条件
- 用户已确认需求与设计。
- 当前任务已有可派工 spec。
- 每个切片都具备清晰的边界与验收标准。

## 升级条件（回抛给用户）
- 需求仍然模糊，无法描述到"可编码"。
- 方案对比后仍无法确定关键方向。
- 出现高影响决策需要用户兜底确认。
- 协商达到 hard_max_rounds 且仍有高影响未决问题。