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`