---
name: issue-verify
description: >
  Issue 状态变更与验证记录。当用户说"验证一下这个 issue"、"issue 验证通过了"、
  "这个问题修好了"、"还没修好"、"Reopen 这个 issue"、"部分修复了"、
  "关掉这个 issue"、"把 issue 状态改成 xxx"时立即触发。
  也适用于 fix-issue 完成后需要记录修复结果、用户回归测试后反馈结果、
  或任何需要变更 issue 状态的场景。
  即使没有明确说"验证"，只要用户在反馈 issue 的修复效果就应触发。
---

# issue-verify: Issue 状态变更与验证记录

统一处理 issue 的状态变更，结构化记录用户原意、修复历程和验证结果。你不是在「改一个字段」——你在为 issue 的生命周期补充关键上下文，让未来的读者理解「为什么这么改、改了什么、用户是否满意」。

---

## 核心原则

1. **结构化记录**：每次状态变更都是一条完整记录，包含上下文（谁改的、为什么改、改了什么）
2. **保留用户原意**：记录用户最初想要什么、现在是否满意——这是最有价值的反馈
3. **不丢历史**：追加而非覆盖。旧记录是宝贵的问题追踪信息
4. **一次一事**：每个 issue 单独处理，不要批量变更时混在一起

---

## 状态规范

| 状态 | 含义 | 终态（可归档） |
|------|------|---------------|
| `Open` | 待处理 | 否 |
| `Pending` | 已修复，等待用户验证 | 否 |
| `Partial` | 部分修复，仍有残留问题 | 否 |
| `Reopen` | 曾修复但问题复现 | 否 |
| `Fixed` | 已修复（开发者确认），待用户验证 | 否 |
| `Verified` | 用户已验证通过 | 是 |
| `Closed` | 关闭（不修复/废弃/非 Bug 类已完成）| 是 |

**合法转换**：

```
Open → Pending | Fixed | Partial | Closed
Pending → Verified | Reopen | Partial | Closed
Fixed → Verified | Reopen | Partial | Closed
Partial → Fixed | Pending | Reopen | Closed
Reopen → Fixed | Pending | Closed
Verified → Reopen（问题回归）
Closed → Reopen（重新打开）
```

---

## 工作流程

### 阶段一：定位 Issue

1. 用户通过 `$ARGUMENTS` 提供引用——可能是文件名、关键词、标题片段、或 `spec/issues/` 中的路径
2. **如果用户给了明确路径**（如 `spec/issues/2026-06-01-xxx.md`）→ 直接 Read
3. **如果用户给了模糊引用**（如"那个 streaming 的 issue"、"昨天的 issue"）→ 用 Grep 在 `spec/issues/` 中搜索匹配
4. **如果找不到** → 在 `spec/archive-issues/` 中也搜索一次（可能已归档）
5. 读取 issue 文件，提取当前状态和内容

**找不到时**：告知用户未找到匹配 issue，建议用 `/issue-create` 先创建。不要猜测。

### 阶段二：确认变更意图

基于用户输入和当前状态，确认要做什么：

**场景 A：用户明确说了目标状态**（如"验证通过"、"改成 Reopen"）
→ 直接确认意图，跳到阶段三

**场景 B：用户反馈了修复效果，没说状态**
→ 根据反馈推断目标状态：

| 用户反馈 | 推断状态 |
|---------|---------|
| "好了"、"修好了"、"验证通过"、"没问题了" | `Verified` |
| "还是不行"、"没修好"、"又出现了" | `Reopen` |
| "部分好了"、"XX 修了但 YY 还有问题" | `Partial` |
| "不用修了"、"关了吧"、"不做了" | `Closed` |
| "修完了等验证"、"代码已改待验证"、"等待验证" | `Pending` |

用 AskUserQuestion 确认推断：

> "我理解你想把这个 issue 标记为 [推断状态]，对吗？
> - A) 是的
> - B) 不对，我想改成其他状态"

### 阶段三：收集验证详情

根据目标状态，收集不同粒度的信息：

**→ Verified（验证通过）**

问用户：
1. 验证通过的具体表现是什么？（用户期望的效果是否达到）
2. 有没有额外发现？（修复是否引入了新问题）

**→ Reopen（验证失败）**

问用户：
1. 当前表现是什么？（与原始 issue 描述是否一致、有无新症状）
2. 是否在特定条件下才复现？

**→ Partial（部分修复）**

问用户：
1. 哪部分修好了？
2. 哪部分还有问题？
3. 残留问题的表现是什么？

**→ Closed（关闭）**

问用户：
1. 关闭原因？（不修复 / 已废弃 / 不是 bug / 已有其他方案）

**→ Pending（等待验证）**

问用户：
1. 修复了什么？（概要）
2. 涉及哪些文件/commit？
3. 用户原意是什么？（用户最初想要什么效果）

**→ Fixed（开发者标记已修复）**

问用户：
1. 修复了什么？（概要）
2. 涉及哪些文件/commit？
3. 用户原意是什么？（用户最初想要什么效果）

### 阶段四：更新 Issue 文档

按以下步骤更新 issue 文件：

**步骤 1：更新状态头部**

将 `**状态**：旧状态` 改为 `**状态**：新状态`。

如果新状态是 `Reopen`，在头部追加 `**Reopen 日期**：YYYY-MM-DD`（如有多个 Reopen，用逗号追加日期）。

**步骤 2：追加状态变更记录**

在「状态变更记录」表格末尾追加一行：

```markdown
| YYYY-MM-DD | 旧状态 | 新状态 | [操作人] | [简述原因] |
```

如果 issue 没有「状态变更记录」段落（旧格式 issue），在文档末尾（`## 涉及文件` 之后、或文档最后）追加该段落，并将历史转换补齐为：

```markdown
## 状态变更记录

| 日期 | 从 | 到 | 操作人 | 说明 |
|------|-----|-----|--------|------|
| 创建日期 | — | Open | [创建者] | 创建 |
| YYYY-MM-DD | Open | [中间状态] | ... | ...（根据文档内容推断历史） |
| YYYY-MM-DD | 旧状态 | 新状态 | [当前操作人] | [本次变更原因] |
```

**步骤 3：追加修复记录（仅 Fixed 状态变更时）**

如果是 `→ Fixed` 或 `→ Verified`（隐含经过 Fixed），在「修复记录」段落追加：

```markdown
### 修复 #N（YYYY-MM-DD）

- **操作人**：[agent / 用户名]
- **用户原意**：[用户希望达到什么效果——用用户自己的话概括]
- **修复内容**：[做了什么改动]
- **涉及 commit**：[commit hash，如有]
- **验证状态**：[待验证 / 已验证 / 验证失败]
```

其中 `#N` 为递增序号（从文档中已有条目数 +1）。用户原意从 issue 的「问题描述」或用户的当前反馈中提取。

如果是 `→ Verified` 且该 issue 已有修复记录但验证状态仍为「待验证」，则**更新最近一条修复记录的验证状态为「已验证」**，而不是新建记录。

如果 issue 没有「修复记录」段落（旧格式 issue），在「状态变更记录」之后追加该段落。

**步骤 4：追加验证详情（仅 Verified / Reopen / Partial 时）**

在「症状详情」段落末尾追加验证反馈子段：

```markdown
### 验证 #N（YYYY-MM-DD）—— [结果]

[用户反馈的详情：期望效果是否达到、当前表现、残留问题等]
```

### 阶段五：输出摘要

```
✅ Issue 状态已更新 → spec/issues/YYYY-MM-DD-<slug>.md

旧状态 → 新状态
变更原因：[一句话]
更新内容：
  - 状态变更记录 +1
  - 修复记录 +N（如适用）
  - 验证详情（如适用）
```

---

## 常见场景示例

### 场景 1：fix-issue 完成后标记 Fixed

用户说：`streaming 的那个 issue 修好了`

Agent 执行：
1. Grep 搜索 `spec/issues/` 找到匹配 issue
2. 读取，当前状态 `Open`
3. 推断目标：`Fixed`
4. 收集修复信息：修了什么、涉及文件、用户原意
5. 更新：`Open → Fixed`，追加修复记录 `#1`，状态变更记录 +1

### 场景 2：用户验证通过

用户说：`刚才那个 issue 验证通过了，没问题`

Agent 执行：
1. 找到 issue，当前状态 `Fixed`
2. 确认转换：`Fixed → Verified`
3. 更新最近修复记录的验证状态为「已验证」
4. 追加状态变更记录 + 验证详情

### 场景 3：用户反馈没修好

用户说：`那个 popup 的 bug 还在，我试了一下还是会崩`

Agent 执行：
1. 找到 issue，当前状态 `Fixed`
2. 确认转换：`Fixed → Reopen`
3. 收集复现信息：用户看到的症状
4. 追加验证详情（验证失败 + 当前表现）
5. 追加状态变更记录

### 场景 4：批量验证（多个 issue）

用户说：`把那几个 hook 相关的 issue 都标记为 Fixed`

Agent 对每个 issue 独立执行阶段三至五，输出汇总报告。每个 issue 的修复记录分别追加，不合并。

---

## 注意事项

- **不要删除或覆盖已有内容**——所有更新都是追加
- **旧格式 issue**（没有「状态变更记录」/「修复记录」段落）→ 在末尾补建段落
- **归档 issue**（`spec/archive-issues/` 中的）→ 拒绝变更，建议创建新 issue 关联
- **状态已经是目标状态** → 提示用户"已经是该状态"，但仍可追加验证详情
