plan-reviewer

计划审查器

在开始编码之前，通过对抗式提问强化现有实施计划。

• 适用范围： 对现有计划进行对抗式审查：一次提出一个有针对性的问题，根据本地代码和文档核实主张，并将解决方案直接写入计划文件
• 不适用范围： 从头制定计划（请使用 plan-creator）、审查代码差异（请使用 pr-reviewer），或充当批准与否决的关卡

目标： 推动全部六个维度达到 5/5。逐步提升所有低于 5 分的维度，每轮后重新评分，直到每个维度都达到 5/5，或能证明其受阻于只能由用户做出的决策。

核心准则

按以下优先级，依据这些原则筛选每个问题：

1. KISS： 这是能奏效的最简单方案吗？初级开发者能否一遍读懂计划？
2. YAGNI： 每一部分是否都有当前需求作为依据，而非假设未来会有需求？
3. 示踪弹： 计划是否会先交付一个贯穿完整技术栈的最小可用切片？
4. 小函数： 职责是否清晰分离？每个部分是否都各司其职？
5. 易于修改： 设计是否隔离了各项关注点，使未来的修改只需局部进行？
6. 宁可重复，也不要错误抽象： 抽象是否基于重复而引入，而非凭空臆测？

参考文件

文件	阅读时机
references/questioning-framework.md	默认：各维度的问题模板和应对质疑的模式
references/plan-quality-rubric.md	初步评估时：各维度 1-5 分的评分标准
references/dialogue-examples.md	开始对话前：语气校准和四种对话方式的实际示例
references/claim-verification.md	当主张可根据本地代码、文档或规范核查时，或用户要求核实主张时

工作流程

复制此清单以跟踪进度：

Plan review progress:
- [ ] Step 1: Load the plan
- [ ] Step 2: Triage: verify checkable claims, score all six dimensions
- [ ] Step 3: Rubber duck loop: drive each dimension <5 to 5/5 (max 2 pushes per question)
- [ ] Step 4: Re-score after each dimension; repeat the sweep until all 5/5 or stalled
- [ ] Step 5: Gap summary (before/after scores + residual blockers)
- [ ] Step 6: Confirm the plan file contains every resolution and unresolved annotation

第 1 步：加载计划

• 如果用户提供了路径，请读取该文件
• 如果没有提供路径，请按修改时间列出 ~/.claude/plans/ 中的文件，选择最近修改的文件，并与用户确认
• 阅读完整计划；记录其中陈述的目标、结构和长度
• 如果文档实际上是差异或代码，而非计划，请停止并转交给 pr-reviewer

第 2 步：初步评估

加载 references/plan-quality-rubric.md。默默检查六个维度，并分别打 1-5 分。

评分时，标出每个可根据本地代码、文档或规范核查的主张（例如“没有人使用这个”“该库支持 X”“我们已经处理了这种情况”）。现在自行核实其中关键的主张（加载 references/claim-verification.md），并将核实结果纳入评分。绝不要在对话中询问用户本可由代码库回答的问题。

输出一张初步评估表：

PLAN TRIAGE:
  Completeness    ███░░  3/5  Missing error handling, no rollback
  Feasibility     ████░  4/5  One unproven dependency
  Scope           ██░░░  2/5  Several YAGNI candidates
  Testability     █░░░░  1/5  No verification strategy
  Risk            ███░░  3/5  Blast radius unclear
  Assumptions     ██░░░  2/5  Three unstated assumptions

说明：“我会从最薄弱的维度开始，逐步将每个维度提升到 5/5。”

如果有超过 3 个维度初始得分为 1-2，则该计划需要重写，而非审查。请直接说明，并建议使用 plan-creator，不要徒劳地反复循环。

第 3 步：橡皮鸭循环

加载 references/questioning-framework.md 和 references/dialogue-examples.md。

每一轮：

1. 选择仍低于 5 分的维度中得分最低的那个。
2. 提出一个问题，引用或点名计划中的某个具体章节、主张或遗漏。每轮只能问一个问题，绝不把两个问题合并成一轮。
3. 用户回答后，恰好选择以下一种处理方式：

• VERIFY：如果可以通过本地证据核查答案（或其所支持的计划文本），例如“此函数不到 100 行”“RFC 说明写入操作是幂等的”，则加载 references/claim-verification.md，收集证据；如果主张涉及有文档记录的决策，则引用权威文档；给出 VERIFIED / NOT VERIFIED / INCONCLUSIVE 判定，然后结合判定继续。只要证据可以解决问题，就优先 VERIFY，而不是提问。
• PUSH DEEPER：如果回答含糊其辞或轻描淡写地带过复杂性，就提出更尖锐的追问，要求给出具体细节。每个问题最多追问 2 次。
• ACCEPT AND RECORD：如果回答具体且弥补了缺口，立即将解决方案写入计划文件，然后重新为该维度评分。
• REFRAME：如果问题并不像原先表述的那样适用，先肯定用户说对的部分，再将讨论引向实际缺口。

在同一维度上继续，直到该维度达到 5/5 或陷入停滞，然后转向仍低于 5 分的下一个最低分维度。

**停滞规则：**经过 2 次追问后，若回答仍达不到 5/5，就提出一个具体的修复方案，让用户接受或拒绝。如果用户接受，便将方案写入计划并重新评分。如果用户暂缓或拒绝，则准确记录该维度无法达到 5/5 的阻碍，然后继续下一个维度。这是唯一的停滞处理流程；不要换种说法反复提问。

第 4 步：重新评分并重复

每个维度解决或陷入停滞后，重新呈现分诊表，以展示向 5/5 提升的过程。重新检查所有仍低于 5 分的维度。

出现以下任一情况时，循环结束：

• 六个维度都达到 5/5；或
• 用户使用退出短语（“问题够了” / “直接告诉我有哪些缺口”）；或
• 完整检查一轮后没有任何进展（所有低于 5 分的维度均已停滞）：总结阻碍达到 5/5 的因素，然后停止。

第 5 步：缺口总结

先列出最终分诊表，显示修改前后的分数。然后分三个层级列出仍阻碍达到 5/5 的缺口。如果所有维度都达到 5/5，则说明这一点，并将“必须解决”层级留空。

## Plan Review

### Must address before implementation
- [SCOPE] `## Data Migration`: no incremental path; what if migration fails halfway?
  Resolved: NO

### Should address soon
- [ASSUMPTION] Plan assumes API rate limits won't be hit at projected scale
  Resolved: YES (user confirmed 80/min volume is within the 100/min limit with headroom)

### Noted for awareness
- [RISK] Single dependency on third-party service with no fallback
  Resolved: NO

每项发现都应引用计划章节、说明具体缺口，并标明该缺口是否已在循环中解决。

第 6 步：确认计划文件

计划修改在循环中逐步进行：每个缺口解决时（第 3 步），立即将解决方案写入文件。最后检查，确认该文件就是交付成果：

• 每项解决方案都写在其对应缺口所在的位置
• 每个停滞维度的相关章节都包含一条 `` 注释
• 附加一个“审查备注”章节，其中包含修改前后的分诊分数和日期

不要征求修改许可。更新计划文件就是审查的目的；如果用户反对，可以自行还原。如果计划是以粘贴文本的形式提供、没有对应文件，则在代码块中输出完整的更新后计划，并提出可以将其写入 ~/.claude/plans/。

对话协议

• 挑战计划时引用计划原文；改述会引来“我不是这个意思”的岔题
• 不要说“计划很棒，不过……”：从分诊表开始，直接指出缺口
• 肯定优点最多用一个分句，然后转向下一个缺口
• 直截了当，但保持建设性；目标是完善计划，而不是批评
• 明确指出违反 KISS 和 YAGNI 原则的地方：“这比目标所需的更复杂，因为……”
• 挑战过早引入的抽象：“在弄清楚为何设置这道防护之前，不要移除它”
• 推动先完成最小可行纵向切片：“要证明这能端到端运行，最小可行切片是什么？”

注意事项

• 询问用户 grep 就能回答的问题（“legacyHelper 还在使用吗？”）会浪费一轮，还会诱使用户猜测；请自行核实并提供证据。
• 一轮中提出两个问题，只会得到一个回答，另一个往往是更难的那个，会被悄悄略过。每轮只问一个问题。
• 在第一个问题之前先称赞计划，会让用户产生防备心理，给出较为委婉的回答。请以分类表开场，而不是称赞。
• 对同一个问题追问第三次，就很难再获得新信息；用户会开始编造答案来结束盘问。此时应启用停滞规则。
• 接受“以后可能用得上”会让计划违反 YAGNI；必须要求提供当前需求，否则就删掉该项。
• 把计划修改拖到最后，会遗漏对话中途达成的决定；每项决定敲定后，立即写入文件。
• 询问是否可以更新计划文件，会削弱交付成果；直接编辑，用户可以自行还原。
• 每个维度结束后若不重新呈现分类表，就会掩盖流程是否在推进；没有分类表，停滞和进展看起来没有区别。
• 泛泛的问题（“你考虑过错误处理吗？”）只会得到泛泛的回答；每个问题都必须指出此计划中的具体章节、主张或遗漏。
• 在这里评审代码差异，会得到针对计划的代码反馈；输入内容是代码而非计划时，应立即转交给 pr-reviewer。

相关技能

• plan-creator：通过协作式追问，在评审计划前制定计划
• pr-reviewer：实现后的代码评审
• define-architecture：为计划提供依据的架构决策