---
name: declarative-openspec-loop
description: 声明式编程循环 - 用户提供校验方式，Agent 自动 propose/apply/校验并迭代直到通过。Use when the user provides expectations or a verification method and wants the agent to implement, verify, and iterate until expectations pass. Triggers on 声明式编程、按预期循环、做到校验通过、declarative loop.
---

# 声明式 OpenSpec 循环

用户提供**判断结果是否符合预期的方式**，Agent 按 OpenSpec 流程 propose → apply → 校验，不通过则分析原因并迭代，直到通过。通过后输出变更点与思路。

**前置**：需要 openspec CLI 及三个子 skill。预期/校验写法的详细说明和端到端示例见 [reference.md](reference.md)。

---

## 何时使用

- 用户说「按我给的预期/校验方式做，做到通过为止」
- 用户提供了校验命令、预期文档、校验清单或自由描述，并希望自动迭代
- 用户提到「声明式编程」「按预期循环」「做到校验通过」

---

## 输入：预期与校验方式

用户必须提供**如何判断结果符合预期**（可组合）：

| 形式     | 示例                                          |
| -------- | --------------------------------------------- |
| 校验命令 | `make test-one2`，退出码 0 即通过             |
| 预期文档 | `docs/tmp/expect_desc.md` 中的校验项表格      |
| 校验清单 | 日志须含 `阶段2 圆弧起点`、`阶段3 右边竖边` … |
| 自由描述 | 「拟合轮廓与 PLY 逆时针顺序一致」             |

若用户未给清，**必须先问**。详细格式说明见 [reference.md § 预期/校验方式](reference.md#预期校验方式的写法)。

---

## 如何调用子 skill（关键）

本 skill 编排三个子 skill，每次调用子 skill 时**必须先读取对应 SKILL.md 并遵循其中的完整步骤**：

| 步骤 | 子 skill              | 读取路径                                        |
| ---- | --------------------- | ----------------------------------------------- |
| 探索 | openspec-explore      | `.cursor/skills/openspec-explore/SKILL.md`      |
| 提案 | openspec-propose      | `.cursor/skills/openspec-propose/SKILL.md`      |
| 实现 | openspec-apply-change | `.cursor/skills/openspec-apply-change/SKILL.md` |

**不要凭记忆执行子 skill 的流程**，每次都读取最新的 SKILL.md 再做。

---

## 主流程

```
用户输入：目标 + 校验方式
        │
        ▼
  1. 初始化：change 名称 + docs/tmp/<name>/ + expectation.md
        │
        ▼
  2. [可选] explore：目标复杂/模糊时先探索
        │
        ▼
  3. propose：生成 proposal / design / tasks（任务带验收标准）
        │
        ▼
  4. apply：按 tasks 实现
        │
        ▼
  5. 校验 ──通过──▶ 6a. 完成：输出变更与思路
        │
      不通过
        │
        ▼
  6b. 分级处理（见下）──▶ 回到 4 或 3
```

---

## 迭代分级：失败后怎么做

校验不通过时，**根据失败根因选择不同路径**，避免小 bug 也走完整提案流程：

### Level 1：代码小修复（最常见）

**触发**：编译错误、运行时 bug、坐标写反、off-by-one、日志格式不对等实现层面问题。

**动作**：

1. 定位出错代码，直接修复
2. 重新编译（若适用）
3. 回到**步骤 5 校验**

不需要 explore，不需要修改 proposal/design/tasks。

### Level 2：任务遗漏或不完整

**触发**：某个校验项没有对应的 task、task 描述模糊导致实现偏差。

**动作**：

1. 分析缺失的校验项对应什么工作
2. 在 `tasks.md` 中**补充或修正** task
3. 回到**步骤 4 apply** 执行新增/修正的 task → **步骤 5 校验**

### Level 3：设计级问题（最少见）

**触发**：整体方向错误、架构不合适、预期理解有偏差、多个校验项系统性失败。

**动作**：

1. 读取子 skill **openspec-explore** 并执行：基于校验结果 + 当前 proposal/design 分析根因
2. 将分析写入 `docs/tmp/<change-name>/iteration_<N>.md`
3. 修订 proposal.md / design.md / tasks.md（在原有 change 上修改，不新建）
4. 回到**步骤 4 apply** → **步骤 5 校验**

### 判断依据

| 信号                                     | Level  |
| ---------------------------------------- | ------ |
| 编译报错                                 | 1      |
| 运行崩溃 / 段错误                        | 1      |
| 单个校验项不通过，其余都通过             | 1 或 2 |
| 多个校验项不通过，但原因各异             | 2      |
| 多个校验项不通过，原因相同（方向性错误） | 3      |
| 校验项全部不通过                         | 3      |

---

## 最大迭代次数

- 默认上限：**5 轮**（一轮 = 一次 apply + 一次校验）。
- 到达上限后**暂停并询问用户**：展示当前进度、未通过的校验项、已尝试的修复方向，让用户决定是否继续。
- 用户可在初始化时指定不同的上限（如「最多跑 3 轮」「不限轮次」）。
- Level 1 的小修复（如编译错误修复后重新编译）**不计入**轮次，仅 apply+校验 计一轮。

---

## 编译失败处理

对于需要编译的项目（C/C++、Rust、Go 等）：

1. apply 完成后、运行校验命令前，**先编译**（或校验命令本身触发编译）。
2. 若编译失败：属于 **Level 1**，直接修复编译错误，重新编译，不计入迭代轮次。
3. 若编译成功但校验不通过：按正常分级处理。
4. 编译错误的修复**不需要** explore 或修订 proposal。

---

## 重复失败检测

若连续 **2 轮**校验结果中，**同一个校验项以相同原因失败**：

1. 停止自动迭代
2. 向用户报告：哪个校验项、什么错误、已尝试的两次修复各做了什么
3. 请用户给出新方向或手动介入

避免 Agent 在同一个坑里反复打转。

---

## 恢复 / 续接

对话中断后重新进入时：

1. 检查 `docs/tmp/<change-name>/` 下已有的 `iteration_*.md` → 确定当前轮次
2. 检查 `openspec/changes/<name>/tasks.md` 中 `[x]` / `[ ]` → 确定 task 进度
3. 读取最近一轮的 `iteration_<N>.md` 和 `check_result_<N>.txt` → 了解上次失败原因
4. 从上次中断的步骤继续，不从头开始

---

## TodoWrite 跟踪

整个循环过程中用 **TodoWrite** 跟踪进度：

```
示例 todo 列表：
- [x] 初始化 change + expectation.md
- [x] propose: 生成 proposal/design/tasks
- [in_progress] 第 1 轮 apply + 校验
- [ ] 校验通过 → 输出变更摘要
```

每轮 apply + 校验 为一个 todo；校验不通过时更新 todo 内容（如「第 1 轮：3/8 校验项通过，Level 2 修复中」）。

---

## 过程数据存储

根目录：`docs/tmp/<change-name>/`

| 文件                     | 内容                                               |
| ------------------------ | -------------------------------------------------- |
| `expectation.md`         | 校验方式摘要（或引用路径）                         |
| `iteration_<NNN>.md`     | 每轮：apply 要点、校验结果、失败项、分级、修复动作 |
| `check_result_<NNN>.txt` | 校验命令原始输出                                   |
| `iteration_final.md`     | 通过后的最终摘要（可选）                           |

若 `docs/tmp` 不存在，先创建。

---

## 输出模板（校验通过时）

```markdown
## 声明式循环完成

**Change:** <change-name>
**校验方式:** <摘要>
**迭代轮次:** N

### 变更摘要

- <文件 1>：<改动>
- <文件 2>：<改动>

### 思路

<设计取舍、与预期的对应、关键实现要点>

### 过程数据

`docs/tmp/<change-name>/`
```

---

## Guardrails

- **未提供校验方式时**：不进入循环，先问用户。
- **每轮校验结果必须落盘**：至少记录通过/不通过与未满足项。
- **优先复用同一 change**：修订 proposal/design/tasks，不盲目新建。
- **任务带验收标准**：propose 时每个 task 尽量带可执行的验证步骤。
- **explore 只分析不改代码**：改代码通过 apply 或 Level 1 直接修复。
- **最大轮次到达时停下问用户**：不自动放弃也不无限跑。
- **重复失败时升级**：同一错误连续 2 轮 → 停下问用户。
- **用户可随时中断**：暂停并汇报当前状态。