# re-03 意见调整完成报告

## 一、调整概述

根据 `reply/re-03.md` 中提出的意见，已完成对 commands 和 SKILL.md 的调整。

---

## 二、调整内容详情

### 2.1 init 命令执行顺序优化

**问题**：原设计中先执行 `aide env ensure` 再执行 `aide init`，但 env 检查需要配置文件，而配置文件在 init 时创建，存在逻辑矛盾。

**解决方案**：拆分 env 检查为两个阶段：

1. **aide env ensure --runtime**
   - 仅检查 aide 程序自身运行环境
   - 不依赖项目配置文件
   - 确保 Python 等基础环境可用

2. **aide init**
   - 创建 `.aide/` 目录
   - 生成默认配置文件
   - 更新 `.gitignore`

3. **aide env ensure**
   - 读取项目配置文件
   - 检查项目开发环境
   - 输出项目配置信息

**调整文件**：
- `aide-marketplace/aide-plugin/commands/init.md`
- `aide-marketplace/aide-plugin/skills/aide/SKILL.md`
- `aide-requirements.md`

---

### 2.2 prep 和 exec 流程指导优化

**问题**：prep 和 exec 命令中主动向 LLM 提示 git 操作、状态记录等内容，但这些已经被 `aide flow` 封装，LLM 不应该关注这些自动化操作。

**解决方案**：

1. **移除主动提示**：不再在 commands 中提示 LLM 关注 git 操作和状态记录
2. **添加注意事项**：在 prep.md 和 exec.md 末尾添加注意事项，明确说明：
   - 不要主动提及 git 操作
   - 不要主动提及状态记录
   - 专注于核心工作（prep 专注任务分析优化，exec 专注任务实现）

**调整文件**：
- `aide-marketplace/aide-plugin/commands/prep.md`
- `aide-marketplace/aide-plugin/commands/exec.md`

---

### 2.3 prep 流程追踪启动时机调整

**问题**：原设计中 prep 在确定任务文档后才启动流程追踪，但应该在最开始就执行 `aide flow`。

**解决方案**：

1. **调整执行顺序**：
   - 先执行 `aide flow start task-optimize "开始任务准备: <任务简述>"`
   - 再确定任务文档路径
   - 然后读取任务文档内容

2. **更新环节名称**：
   - prep 阶段使用 `task-optimize` 环节
   - exec 阶段使用 `flow-design` / `impl` / `verify` / `docs` / `finish` 环节

**调整文件**：
- `aide-marketplace/aide-plugin/commands/prep.md`
- `aide-marketplace/aide-plugin/skills/aide/SKILL.md`
- `aide-requirements.md`

---

### 2.4 参数传递支持

**问题**：prep 和 exec 命令应该支持传入文档路径参数，未传入时使用配置文件中的默认路径。

**解决方案**：

1. **prep 命令参数**：
   - 参数：`[任务原文档路径]`（可选）
   - 未传入时：使用 `aide config get task.source` 获取默认路径（通常为 task-now.md）

2. **exec 命令参数**：
   - 参数：`[任务细则文档路径]`（可选）
   - 未传入时：使用 `aide config get task.spec` 获取默认路径（通常为 task-spec.md）

**调整文件**：
- `aide-marketplace/aide-plugin/commands/prep.md`
- `aide-marketplace/aide-plugin/commands/exec.md`
- `aide-requirements.md`

---

## 三、文件修改清单

### 3.1 Commands 文件

| 文件 | 主要修改 |
|------|---------|
| `init.md` | 1. 添加 `--runtime` 参数说明<br>2. 调整执行顺序为：runtime检查 → init → 项目认知 → 项目环境检查 |
| `prep.md` | 1. 调整流程追踪启动时机到最开始<br>2. 添加参数说明<br>3. 添加注意事项（不主动提及git和状态记录） |
| `exec.md` | 1. 添加参数说明<br>2. 添加注意事项（不主动提及git和状态记录） |

### 3.2 SKILL.md 文件

| 修改项 | 内容 |
|-------|------|
| aide env ensure | 添加 `--runtime` 参数说明 |
| aide flow start | 更新环节名称列表，添加 `task-optimize` |
| 环节名称列表 | 添加使用场景列，区分 prep 和 exec 阶段 |
| 常见用法示例 | 拆分为 prep 阶段示例和 exec 阶段示例 |

### 3.3 aide-requirements.md 文件

| 章节 | 修改内容 |
|------|---------|
| 4.1 /aide:init | 添加执行顺序说明，明确三步流程 |
| 4.2 /aide:prep | 添加参数说明，更新职责列表，添加流程管理说明 |
| 4.3 /aide:exec | 添加参数说明，明确各环节名称，添加运行特点说明 |
| 5.1 aide flow | 更新环节名称列表，添加使用场景列 |
| 5.3 aide env | 添加 `--runtime` 参数说明 |

---

## 四、设计改进总结

### 4.1 解决的核心问题

1. **环境检查依赖问题**：通过 `--runtime` 参数解决了配置文件依赖的循环问题
2. **信息污染问题**：明确 LLM 不需要关注自动化操作，专注核心业务
3. **流程完整性**：prep 阶段从一开始就启动流程追踪，保证完整性
4. **灵活性提升**：支持参数传递，同时保持默认配置的便利性

### 4.2 设计原则体现

1. **确定性封装**：git 操作和状态记录完全由程序处理
2. **渐进式披露**：LLM 只看到必要的信息，不被实现细节干扰
3. **关注点分离**：Commands 专注流程指导，Skills 专注工具说明

---

## 五、后续建议

### 5.1 需要在程序实现中注意的点

1. **aide env ensure --runtime**
   - 必须不依赖任何配置文件
   - 只检查 Python、pip/uv 等基础环境
   - 失败时给出明确的修复建议

2. **aide flow 环节校验**
   - 需要区分 prep 和 exec 阶段的环节
   - task-optimize 只能在 prep 阶段使用
   - flow-design/impl/verify/docs/finish 只能在 exec 阶段使用

3. **配置文件默认值**
   - task.source 默认为 "task-now.md"
   - task.spec 默认为 "task-spec.md"
   - 这些默认值应该在 aide init 时写入配置文件

### 5.2 文档完整性检查

所有调整已完成，文档之间保持一致：
- ✅ Commands 与 SKILL.md 一致
- ✅ Commands 与 aide-requirements.md 一致
- ✅ SKILL.md 与 aide-requirements.md 一致

---

## 六、验证要点

在实际使用时，应验证以下场景：

1. **init 流程**：
   - 在没有 Python 的环境下，`aide env ensure --runtime` 应该报错
   - 在没有配置文件的情况下，`aide init` 应该成功创建
   - 创建配置文件后，`aide env ensure` 应该能读取配置

2. **prep 流程**：
   - 不传参数时，应该使用配置中的默认路径
   - 传入参数时，应该使用指定路径
   - 整个过程不应该有 git 操作的提示

3. **exec 流程**：
   - 环节跳转应该符合预期流程
   - flow-design 环节应该检查 PlantUML 语法
   - docs 环节应该检查 CHANGELOG 更新

---

## 七、总结

本次调整完全响应了 re-03 中提出的所有意见：

1. ✅ 解决了 init 命令的执行顺序问题
2. ✅ 移除了 prep 和 exec 中对 git 操作的主动提示
3. ✅ 调整了 prep 的流程追踪启动时机
4. ✅ 添加了参数传递支持

所有修改都遵循了 aide 系统的核心设计原则，保持了文档的一致性和完整性。