From ad38360f4ef6816f054eb4a207cf851f48f4f02a Mon Sep 17 00:00:00 2001
From: Origami404 <Origami404@foxmail.com>
Date: Thu, 9 Apr 2026 11:27:50 +0800
Subject: [PATCH] docs: add organized feedback skill design spec

---
 ...6-04-09-organized-feedback-skill-design.md | 160 ++++++++++++++++++
 1 file changed, 160 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-04-09-organized-feedback-skill-design.md

diff --git a/docs/superpowers/specs/2026-04-09-organized-feedback-skill-design.md b/docs/superpowers/specs/2026-04-09-organized-feedback-skill-design.md
new file mode 100644
index 0000000..f690bee
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-09-organized-feedback-skill-design.md
@@ -0,0 +1,160 @@
+# 意见整理 Skill 设计（v1）
+
+## 1. 背景与目标
+
+本设计用于新增一个“意见整理”Skill，将 `gitea-pr-review fetch` 产出的 PR Review Markdown 中的非结构化评论，整理为结构化的 `Organized Feedback` 列表，供后续开发决策使用。
+
+目标：
+- 对混杂的审阅意见做统一分类与归并。
+- 允许“拆分或合并”策略由 agent 自主决定。
+- 强制执行覆盖审计，保证不遗漏任何原始 `Comment/Reply`。
+- 最终输出写入用户指定路径。
+
+约束：
+- 当前文档版本规则固定为 `v1`，不做版本 bump。
+
+## 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 仅用于交互，不写最终文件。
+- 必须由用户指定输出路径。