# Rpiv Loop:fix

> 基于 rpiv/todo 下的待办文件进行分析和修复

- Skill: `zhuqingxun/rpiv-loop-fix` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zhuqingxun/rpiv-loop-fix`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhuqingxun/rpiv-loop-fix/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: zhuqingxun (https://skillmd.com/u/zhuqingxun)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhuqingxun/rpiv-loop-fix

---


# Fix: 分析并修复待办条目

读取 `rpiv/todo/` 下的待办文件（支持 issue/feature/todo 三种类型），根据类型执行对应的处理流程，并将处理记录回写到文件中。

## 输入

待办文件路径：$ARGUMENTS

- 必须提供一个有效的待办文件路径（如 `rpiv/todo/issue-some-bug.md`）
- 如果 $ARGUMENTS 为空，列出 `rpiv/todo/` 下所有 status=open 的条目，让用户选择

## 类型分流

读取文件 frontmatter 的 `type` 字段后，按类型执行不同流程：

| 类型 | 流程 |
|------|------|
| `issue` | 阶段 0 → 1 → **1.5（前置对齐）** → 2 → 3 → 4 → 5 → 6 |
| `feature` | 使用 AskUserQuestion 询问用户：① 走 PRD 流程（`/rpiv-loop:create-prd`）② 作为小特性直接实施（阶段 0 → 1 → **1.5（前置对齐）** → 3 → 5 → 6） |
| `todo` | 简化流程：阶段 0 → 1（确认理解）→ **1.5（前置对齐）** → 3（直接执行）→ 5（回写"执行记录"替代"修复记录"）→ 6 |

如果文件没有 `type` 字段（旧文件），从文件名前缀推断（`issue-`/`feature-`/`todo-`），都没有则默认按 `issue` 处理。

**所有类型在阶段 1 之后、进入实施之前，都必须先过「阶段 1.5：与当前系统对齐 + 价值确认」这道强制门槛**（见下）。

## 执行流程

### 阶段 0：读取与状态更新

1. 读取待办文件完整内容
2. 检查 status：
   - `open`：正常流程，更新为 `in-progress`
   - `in-progress`：询问用户是否继续上次未完成的处理
   - `completed`：提示已完成，询问是否需要重新打开
3. 读取 `type` 字段，按"类型分流"章节决定后续流程
4. 更新 frontmatter：
   - `status: in-progress`
   - `updated_at: 当前时间`

### 阶段 1：问题理解

1. **理解问题**：完整阅读 issue 文件中的所有章节
2. **提取关键信息**：
   - 问题现象和错误信息
   - 已知的根本原因（如果有）
   - 已尝试过的方案（避免重复）
   - 影响的文件和模块
3. **向用户确认理解**：用一段话概括问题，确认理解无误后继续

### 阶段 1.5：与当前系统对齐 + 价值确认（强制前置门槛，先于任何实施）

⚠️ **这是进入实施（issue 走阶段 2 / todo·feature 走阶段 3）的强制门槛，所有类型都必须先过。** todo 往往创建较早，随系统不断演进，其中的内容可能已**失效**、需**变更**或应**作废**。**严禁**凭 todo 的历史描述（尤其它自带的"执行记录 / 完成情况"标记）直接实施——那是历史快照，不是 ground truth。

完成以下三步、并经用户确认本轮实施范围后，才能进入实施阶段：

1. **与当前代码对齐（逐条 verify，不信任历史标记）**：对 todo 里**每条**待办 / 事实声明，用 `Grep` / `Read` 实际代码验证当前状态，逐条标三态之一：
   - **仍有效**：痛点仍在、原解法仍合理 → 候选保留
   - **需变更**：系统已变，痛点还在但解法要调整 → 候选保留（附调整说明）
   - **已失效 / 作废**：痛点已消失，或已被其它机制覆盖 / 取代 → 候选淘汰
   - todo 自带的"已完成 / 待办"标记一律**重新核对**，不得直接采信（它可能在写下后又被系统演进推翻）

2. **价值确认（哪些还值得做）**：基于对齐结果，逐条判断当前**真实价值**，给每条一个终态：
   - 价值仍在 → 保留进入实施
   - 价值已被现有机制覆盖 / 边际过低 → 标 `wontfix`（回写时写明"为什么不做"保留追溯）
   - 不在本插件 / 本仓库可独立解决范围 → 转**独立** issue/todo 跟踪
   - 配合全局规则「处理 todo 默认推进到关闭」：每条都要有终态，不留悬空 `deferred`

3. **不清楚处用 AskUserQuestion 对齐**：对齐与价值判断中任何"不够清楚 / 需用户拍板"的点（某条是否仍要做、终态取哪个、本轮实施范围定哪些），**必须用 AskUserQuestion 以选项形式和用户对齐**，禁止凭假设替用户决定。

**产出**：一张"对齐 + 价值"结论表（`条目 | 当前代码实况 | 三态 | 终态处置`），回写到 todo 作为已验证证据。**只有用户确认"本轮做哪些"后**，才带着这个收敛后的范围进入实施阶段；若全部条目都失效 / wontfix，则跳过实施直接走阶段 6 收口归档。

### 阶段 2：代码库分析

1. **定位相关代码**：
   - 根据问题描述搜索相关文件和函数
   - 阅读相关模块的核心逻辑
   - 理解当前的实现方式

2. **根因分析**（如果 issue 中"根本原因"为"待分析"）：
   - 分析问题的技术根因
   - 记录分析过程和结论
   - 使用 AskUserQuestion 确认根因分析结果

3. **制定修复方案**：
   - 列出需要修改的文件清单
   - 说明每个文件的修改要点
   - 评估修复的影响范围（是否会影响其他功能）
   - 使用 AskUserQuestion 确认修复方案

### 阶段 3：实施修复

1. **红测试先行（issue 类 bug 且项目有测试套件时强制）**：动手修复前，先写一个能复现该 bug 的失败回归测试，运行并**展示红色输出**——测试在当前代码上必须失败，且只有 bug 真正修好才会通过。项目无测试套件、或条目为 todo/feature 类执行任务时跳过本步，改在阶段 4 说明验证方式
2. 按照确认的方案逐步修改代码
3. 每个修改点：
   - 说明修改原因
   - 展示修改内容
4. 如果修改过程中发现新问题或方案需要调整，及时与用户沟通

### 阶段 4：验证

1. **红转绿确认**（若阶段 3 写了复现测试）：重跑该测试，展示由红转绿的输出——没有红转绿过程的修复不算验证通过
2. 运行项目的验证命令（如果项目配置了 lint/test/build），确认全量通过
3. 如果无自动化验证，手动检查修改的正确性
4. 确认修复不引入新问题

### 阶段 5：回写修复记录

1. **更新 issue 文件的"根本原因"章节**（如果之前为"待分析"）：
   - 写入分析得出的根因

2. **追加"修复记录"章节**到 issue 文件末尾（在"参考"之前）：

```markdown
## 修复记录

**修复时间**: {YYYY-MM-DD HH:MM:SS}

### 修改文件

| 文件 | 修改说明 |
|------|---------|
| path/to/file1.js | {一句话描述修改内容} |
| path/to/file2.js | {一句话描述修改内容} |

### 修复说明

{2-5 句话概括修复思路和关键变更}

### 验证结果

{验证通过/验证方式说明}
```

3. **更新 frontmatter**：
   - `status: completed`
   - `updated_at: 当前时间`

### 阶段 6：归档与引导

修复完成后，**自动归档**已完成的 todo 文件（不要仅建议用户手动归档）：

1. 创建 `rpiv/archive/` 目录（如不存在）
2. 更新 frontmatter：`status: archived`，添加 `archived_at: 当前时间`，更新 `updated_at`
3. 移动文件到 `rpiv/archive/`（如有同名则加时间戳后缀，如 `issue-bug.20260311_120000.md`）
4. 验证移动成功（目标存在、源已删除）
5. 输出："已归档到 `rpiv/archive/{name}.md`"

然后输出修复总结。

## 特殊情况处理

### 上游/外部问题（无法直接修复）

如果 issue 描述的是上游依赖或外部服务的 bug（如本项目的 Bun 崩溃问题）：

1. 明确告知用户此问题无法在本项目中直接修复
2. 在 issue 文件中记录：
   - "修复记录"章节改为"处理记录"
   - 记录已实施的 workaround（如有）
   - 记录上游 issue 的跟踪链接
3. `status` 更新为 `completed`，在"处理记录"中标注"上游问题，已应用 workaround"或"上游问题，等待官方修复"

### 修复中断

如果修复过程中用户需要中断：
1. 保持 `status: in-progress` 不变
2. 在 issue 文件末尾追加当前进度说明
3. 下次通过 `/rpiv-loop:fix` 重新打开时可继续

### 修复失败

如果分析后发现当前无法修复：
1. 将分析结果写入"根本原因"章节
2. 在"修复记录"改为"分析记录"，记录已尝试的方案和失败原因
3. `status` 保持 `in-progress`（不标记为 completed）
4. 建议用户后续重新尝试或寻求其他方案

## 注意事项

1. **前置对齐先于实施（强制）**：见「阶段 1.5」。未完成"与当前代码对齐 + 价值确认 + 用户对齐本轮范围"前，禁止进入实施阶段（阶段 2/3）改任何代码。todo 越老越要先 verify，不凭历史描述开干
2. **避免重复劳动**：认真阅读 issue 中"已尝试的方案"，不要重走已排除的路径
3. **最小化修改**：只修改解决问题必需的代码，不做额外重构
4. **保持 issue 文件结构**：回写时只追加或更新特定章节，不改动其他内容
5. **修改 rpiv/ 文件后同步更新 frontmatter**：每次修改待办文件都要更新 `updated_at`