gitea-pr-review/docs/superpowers/specs/2026-04-09-organized-feedback-skill-design.md

意见整理 Skill 设计

1. 背景与目标

本设计用于新增一个“意见整理”Skill，将 gitea-pr-review fetch 产出的 PR Review Markdown 中的非结构化评论，整理为结构化的 Organized Feedback 列表，供后续开发决策使用。

目标：

• 对混杂的审阅意见做统一分类与归并。
• 允许“拆分或合并”策略由 agent 自主决定。
• 强制执行覆盖审计，保证不遗漏任何原始 Comment/Reply。
• 最终输出写入用户指定路径。

2. 范围

本 Skill 仅负责：

• 读取单份 PR Review Markdown。
• 产出单份 Organized Feedback Markdown 文档。
• 在交互中展示覆盖审计信息。

本 Skill 不负责：

• 直接修改代码。
• 自动发起二次请求获取更多 PR 数据。

3. 输入与输出

3.1 输入

必需输入：

• 一份符合 gitea-pr-review 输出结构的 Markdown（含 Review/Comment/Reply）。
• 用户指定的输出文件路径（用于写入 Organized Feedback 文档）。

若用户未提供输出路径，Skill 必须先询问并暂停。

3.2 输出

最终输出文档（写入用户指定路径）包含：

• ## Organized Feedback
• ## Unknown Items（仅存在 unknown 时出现）

最终输出文档不包含：

• Coverage Audit（仅在交互过程展示，不落盘）。

4. 分类体系

4.1 主类型

• question：请求解释/澄清，不直接要求修改。
• supplement：补充背景信息，不构成明确修改请求。
• request-for-change：要求实现发生改变。
• unknown：证据不足或语义冲突，且无法通过上下文消歧。

默认倾向：尽量避免 unknown，仅在迫不得已时使用。

4.2 RFC 二级分类

仅当 Type=request-for-change 时填写：

Change-Scope：

• local
• implement
• api-change
• requirement-change

Necessity：

• nice-to-have
• should-fix
• must-fix

5. 处理流程

5.1 阶段 A：预处理

• 扫描输入文档中的全部 Comment/Reply。
• 为每条原始意见建立唯一引用键（例如 R1.C2、R1.C2.P1）。
• 建立 All-Source-Refs 集合。

5.2 阶段 B：归类与归并

• agent 可自主选择粒度：
  • 拆分：一条原始意见拆成多条整理意见。
  • 合并：多条原始意见合并成一条整理意见。
• 允许一条原始意见被多条整理意见引用（多对多）。
• 若同一原始意见同时包含提问与改动请求，优先拆分为独立条目。

5.3 阶段 C：覆盖审计（交互展示）

• 计算 Covered-Source-Refs（被至少一个整理意见引用）。
• 计算差集 Missing-Source-Refs = All - Covered。
• 若差集非空，强制补洞并重复审计，直至差集为空。
• 审计信息在交互中展示，不写入输出文档。

5.4 阶段 D：unknown 反思机制

• 只要存在 unknown（>=1），必须执行一次反思复判。
• 复判后仍无法归类，方可保留为 unknown。
• 若 unknown 绝对数量 > 3：
  • 必须在交互中明确提示“审阅质量或上下文完整性存在风险”。
  • 必须请求用户许可；未获许可不得写最终输出文件。

6. 输出格式

6.1 Organized Feedback 条目格式

每条意见包含：

• Type
• Change-Scope（RFC 必填）
• Necessity（RFC 必填）
• Summary（1-2 句）
• Rationale（分类依据；unknown 时写阻塞原因）
• Source-Refs（引用的原始键）
• Raw-Excerpts（精简原文摘录）

6.2 Unknown Items

当存在 unknown 时，文档追加 ## Unknown Items，每条写明：

• 无法归类的原因。
• 解除不确定性所需的最小补充信息。

7. 错误处理

• 输入结构不可识别：报错并停止；提示已识别段落数与示例片段。
• 输出路径缺失：询问用户并暂停。
• 输出目录不存在：请求确认后创建，或要求用户更换路径。
• 输出不可写：报错并给出替代路径建议。
• 覆盖审计始终无法闭合：停止写文件并在交互中报告未覆盖键。

8. 组件边界与职责

• Parser：提取 Review/Comment/Reply 与引用键。
• Classifier：完成类型判定、RFC 细分与必要性判定。
• Grouper：执行拆分/合并并维持 Source-Refs 映射。
• Auditor：执行覆盖审计与补洞循环。
• Writer：按固定模板写入输出 Markdown。

各组件通过显式结构化中间数据通信，避免隐式状态耦合。

9. 测试与验收标准

最小验收标准：

• 所有原始 Comment/Reply 均被至少一条输出意见覆盖。
• 输出文档不包含 Coverage Audit 区块。
• 当出现 unknown 时，必有反思复判步骤。
• 当 unknown 数量 > 3 时，无用户许可不得落盘。
• RFC 条目完整填写 Change-Scope 与 Necessity。

建议测试集：

• 纯 question 样例。
• question + RFC 混合样例（验证拆分）。
• 多线程同主题样例（验证合并）。
• 高歧义样例（触发 unknown 与用户许可门禁）。

10. 决策记录

• 采用纯 Prompt Skill（不引入脚本）。
• 采用“两阶段归类 + 覆盖审计补洞”策略。
• Coverage Audit 仅用于交互，不写最终文件。
• 必须由用户指定输出路径。