# /aide:prep 命令设计文档

## 一、背景

### 1.1 解决的问题

用户提供的任务描述通常存在以下问题：

| 问题 | 影响 |
|------|------|
| 表述模糊 | 执行方向不明确 |
| 存在歧义 | 可能产生错误理解 |
| 缺少细节 | 执行时需要频繁确认 |
| 多种方案 | 需要用户决策 |

### 1.2 设计目标

将任务描述转化为**清晰、可执行的任务细则**：
- 消除歧义和模糊
- 明确执行步骤和验证标准
- 处理待定项，获取用户决策
- 产出 task-spec.md 供执行阶段使用

---

## 二、职责

### 2.1 做什么

1. 启动流程追踪（task-optimize 环节）
2. 深度分析任务内容
3. 优化任务表述（准确性、简洁性、可执行性）
4. 处理待定项，获取用户确认
5. 生成任务细则（task-spec.md）

### 2.2 不做什么

- 不执行实际的任务实现
- 不编写业务代码
- 不主动关注 git 操作和状态记录（由 aide flow 自动处理）

---

## 三、参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `$ARGUMENTS` | 可选 | 任务原文档路径 |

**未传入参数时**：使用 `aide config get task.source` 获取默认路径（通常为 task-now.md）

---

## 四、执行流程

```
@startuml
skinparam defaultFontName "PingFang SC"

start

:aide flow start task-optimize "开始任务准备: <任务简述>";

:确定任务文档路径;
note right: 使用参数或配置默认值

:读取任务文档;

if (文档存在?) then (是)
else (否)
  :询问用户提供任务内容;
  stop
endif

partition "阶段1: 任务分析" {
  :深度理解任务;
  note right: 核心目标\n交付物\n成功标准\n涉及模块\n技术难点

  :分析项目环境;
  note right: 阅读相关代码/文档\n理解与现有结构的关系

  :aide flow next-step "任务分析完成";
}

partition "阶段2: 任务优化" {
  :准确性优化;
  note right: 识别歧义\n识别隐含假设\n明确边界

  :简洁性优化;
  note right: 识别冗余\n区分真冗余与必要强调

  :可执行性优化;
  note right: 抽象→具体步骤\n明确输入/输出/验证标准

  :生成待定项;

  :aide flow next-step "任务优化完成，生成待定项";
}

partition "阶段3: 待定项处理" {
  if (有待定项?) then (是)
    :aide decide '<json>';
    :告知用户访问链接;
    :aide decide result;
    :aide flow next-step "用户完成待定项确认";
  else (否)
  endif
}

partition "阶段4: 结果生成" {
  :整合生成任务细则;
  :aide flow next-step "生成任务细则，等待用户确认";

  :展示给用户确认;

  if (用户确认?) then (是)
    :保存为 task-spec.md;
    :aide flow next-step "用户确认任务细则";
  else (否)
    :根据反馈调整;
    note right: 返回相应阶段
  endif
}

:aide flow next-step "任务准备完成";

:提示用户执行 /aide:exec;

stop
@enduml
```

---

## 五、阶段详解

### 5.1 阶段1：任务分析

**核心问题**：
- 任务要解决什么问题？
- 最终交付物是什么？
- 成功的标准是什么？
- 涉及哪些模块/系统？
- 是否有技术难点？

**复杂任务处理**：
- 多子目标、多方案对比时，建议使用 sequential-thinking 进行结构化分析

### 5.2 阶段2：任务优化

| 优化维度 | 关注点 |
|----------|--------|
| 准确性 | 歧义、不明确之处、隐含假设、任务边界 |
| 简洁性 | 冗余表述、区分真冗余与必要强调 |
| 可执行性 | 抽象→具体步骤、输入/输出/验证标准、替代方案 |

### 5.3 阶段3：待定项处理

**待定项类型**：
- 存在多种可行方案
- 有歧义需要澄清
- 需要用户确认的决策

**处理流程**：
1. 准备待定项 JSON 数据
2. 调用 `aide decide '<json>'` 启动 Web 服务
3. 告知用户访问链接进行确认
4. 调用 `aide decide result` 获取决策结果

### 5.4 阶段4：结果生成

**任务细则结构**：
```markdown
# 任务细则

## 任务目标
[清晰描述任务要达成的目标]

## 成功标准
[明确的、可验证的成功标准]

## 执行步骤
1. [步骤1]
2. [步骤2]
...

## 技术决策
[已确认的技术选型]

## 约束与边界
[任务范围边界]
```

---

## 六、与 aide 程序的交互

### 6.1 aide flow start

**调用时机**：命令开始时

**命令**：
```bash
aide flow start task-optimize "开始任务准备: <任务简述>"
```

### 6.2 aide flow next-step

**调用时机**：每个阶段完成时

**命令**：
```bash
aide flow next-step "<完成内容简述>"
```

### 6.3 aide config get

**调用时机**：未传入参数时

**命令**：
```bash
aide config get task.source
```

### 6.4 aide decide

**调用时机**：有待定项需要用户确认时

**命令**：
```bash
aide decide '<json数据>'
aide decide result
```

---

## 七、注意事项

1. **不要主动提及 git 操作**：由 aide flow 自动处理
2. **不要主动提及状态记录**：由 aide flow 自动处理
3. **专注于任务分析和优化**：这是 prep 的核心价值

---

## 八、依赖

| 依赖项 | 类型 | 说明 |
|--------|------|------|
| /aide:init | Command | 需要先完成环境初始化 |
| aide flow | aide 子命令 | 流程追踪 |
| aide decide | aide 子命令 | 待定项处理 |
| aide config | aide 子命令 | 读取配置 |

---

## 九、被依赖

| 依赖方 | 说明 |
|--------|------|
| /aide:exec | 使用 prep 产出的 task-spec.md |

---

## 十、修改指南

### 10.1 修改分析/优化流程

1. 更新本文档的阶段详解
2. 修改执行文件 `../../commands/prep.md`

### 10.2 修改任务细则格式

1. 更新本文档的"结果生成"章节
2. 修改执行文件中的模板

### 10.3 修改待定项处理

1. 更新本文档的"待定项处理"章节
2. 如涉及数据格式变更，同步更新 [数据格式文档](../../../../aide-program/docs/formats/data.md)

---

## 十一、相关文档

- [执行文件](../../commands/prep.md)
- [aide flow 设计](../../../../aide-program/docs/commands/flow.md)
- [aide decide 设计](../../../../aide-program/docs/commands/decide.md)
- [数据格式规范](../../../../aide-program/docs/formats/data.md)
- [plugin 导览](../README.md)