rpiv-loop-fix

name	rpiv-loop:fix
description	基于 rpiv/todo 下的待办文件进行分析和修复
argument-hint	[todo 文件路径]
allowed-tools	Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Skill
version	2.17.14

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 文件末尾（在"参考"之前）：

## 修复记录

**修复时间**: {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