doc: comment规范与文档边界治理迭代计划 (Refs #33)

prompts/discuss/033_2026-04-23_comment规范与文档边界治理迭代计划.md

@@ -0,0 +1,366 @@
+# Comment 规范与文档/Comment 边界治理迭代计划
+
+**Issue**: GOV-012 (#33)
+**日期**: 2026-04-23
+**作者**: PMO
+**状态**: 迭代计划
+
+---
+
+## 1. 问题诊断
+
+### 1.1 当前缺口逐项分析
+
+| 缺口 | 严重程度 | 根因 | 当前状态 |
+|------|---------|------|---------|
+| comment 链路不完整 | P1 | prompts 定义了 14 个强制 comment 节点，但未定义 comment 类型模板和链路完整性检查规则 | 002_develop_pipeline.md 有节点列表，无链路检查机制 |
+| Human Review 发起不规范 | P0 | 无独立的 HR 发起 comment 模板，HR 发起与评审结论混为一谈 | human-review.md 有工作流，无发起模板 |
+| comment 模板缺失 | P1 | review-comment-template.md 仅 1 个通用模板，未覆盖 5 种必要 comment 类型 | 模板过于简化 |
+| skill/prompts 文档未覆盖 | P1 | 各 skill 的 SKILL.md 引用 review-comment-template.md，但模板本身不完整 | PM/QA/PMO 的必读文档列表包含模板，但模板不足 |
+| comment 替代文档 | P0 | Issue #19 QA 测试报告仅以 comment 形式发布，无独立 QA 报告文档 | QA skill 要求"测试报告已发布"，但未明确"文档形式"vs"comment 形式"的边界 |
+
+### 1.2 文档覆盖度分析
+
+**Prompts（核心规则）覆盖度**：
+
+| 文档 | comment 规范覆盖 | 缺口 |
+|------|-----------------|------|
+| `002_develop_pipeline.md` | 14 个强制 comment 节点列表 | 无 comment 类型定义、无链路完整性检查、无"严禁 comment 替代文档"规则 |
+| `013_github_issue_and_review_comments.md` | Gate 评论最小字段、评论约束 | 无 comment 模板、无链路定义、无文档/comment 边界规则 |
+| `017_human_review_and_signoff.md` | HR 结论类型（Approved/Conditional/Rejected） | 无 HR 发起 comment 规范、无独立发起模板 |
+| `004_delivery_gates.md` | CI 检查逻辑 | 已废弃 Gate 定义，不覆盖 comment 规范 |
+| `014_process_compliance_and_audit.md` | 合规检查对象包含"Issue 评论是否缺关键 Gate 记录" | 无 comment 模板审计、无文档/comment 边界检查 |
+| `020_issue_comment_gate_and_artifact_linkage.md` | Comment 最小字段、产物关联 | 无 comment 类型定义、无链路定义 |
+| `015_review_evaluation_dimensions.md` | 评审评估维度 | 未关联到 comment 模板 |
+
+**Skills（角色工作流）覆盖度**：
+
+| 文档 | comment 规范覆盖 | 缺口 |
+|------|-----------------|------|
+| `skills/product-manager/SKILL.md` | "Issue 评论只放结构化结论和文档链接"、PRD 阶段评论最小字段 | 无 comment 类型模板引用、无 HR 发起规范 |
+| `skills/qa-engineer/SKILL.md` | "QA 结论必须写回 Issue 评论和 QA report" | 未明确"QA report 必须是独立文档，comment 只是摘要" |
+| `skills/pmo/SKILL.md` | 14 个强制 comment 节点检查 | 无 comment 模板规范、无文档/comment 边界检查 |
+| `skills/workflows/tech-review.md` | "在纪要和关联 Issue 评论中记录评审结果" | 无 comment 类型区分 |
+| `skills/workflows/qa-validation.md` | "把发布准备状态写入关联 issue" | 无 QA 报告文档 vs comment 边界 |
+| `skills/workflows/human-review.md` | "在 issue、纪要或 PR 中留下正式结论" | 无 HR 发起 comment 规范 |
+| `skills/workflows/prd-review.md` | "在纪要和关联 Issue 评论中记录评审结论" | 无 comment 类型区分 |
+
+**Templates**：
+
+| 文档 | 状态 | 缺口 |
+|------|------|------|
+| `skills/templates/review-comment-template.md` | 仅有 1 个通用模板 | 未覆盖 5 种必要 comment 类型 |
+| `skills/templates/qa-report-template.md` | 存在 | 未被明确引用为"必须独立产出" |
+
+---
+
+## 2. Comment 模板规范（5 种必要类型）
+
+### 2.1 评审发起 Comment 模板
+
+```markdown
+## 评审发起: {Gate 名称}
+
+**项目**: {project_id}
+**Issue**: #{N}
+**评审对象**: {文档/PR 名称}
+**发起时间**: {YYYY-MM-DD HH:MM}
+**发起人**: {角色}
+
+### 评审材料
+
+- {材料 1 链接}
+- {材料 2 链接}
+
+### 评审范围
+
+{概括本次评审需要确认的核心内容}
+
+### 期望结论时间
+
+{YYYY-MM-DD}
+
+### 必签角色
+
+- [ ] {角色 1}
+- [ ] {角色 2}
+- [ ] {角色 3}
+
+---
+*此 comment 标记评审正式开始。评审结论请在下方回复。*
+```
+
+### 2.2 评审意见 Comment 模板（含 Conditional Approved）
+
+```markdown
+## 评审意见: {Gate 名称}
+
+**项目**: {project_id}
+**Issue**: #{N}
+**评审对象**: {文档/PR 名称}
+**评审时间**: {YYYY-MM-DD HH:MM}
+**评审人**: {角色} ({Name})
+
+### 结论
+
+`Approved` | `Conditional Approved` | `Rejected`
+
+### 关键意见
+
+{结构化评审意见，按维度分类：完整性 / 一致性 / 逻辑性 / 证据充分性}
+
+### 条件项（仅 Conditional Approved 时填写）
+
+| 序号 | 条件项 | Owner | Due Date | 关闭标准 |
+|------|--------|-------|----------|---------|
+| 1 | {描述} | {Owner} | {日期} | {标准} |
+
+### 行动项
+
+| 序号 | 行动项 | Owner | Due Date |
+|------|--------|-------|----------|
+| 1 | {描述} | {Owner} | {日期} |
+
+### 下游准入
+
+{是否允许进入下游阶段，如不允许需说明原因}
+```
+
+### 2.3 迭代回复 Comment 模板
+
+```markdown
+## 迭代回复: {Gate 名称}
+
+**项目**: {project_id}
+**Issue**: #{N}
+**回复对象**: {上方评审意见 comment 链接}
+**回复时间**: {YYYY-MM-DD HH:MM}
+**回复人**: {角色}
+
+### 本次迭代内容
+
+{概括本次修改了什么、为什么这样改}
+
+### 修改证据
+
+- {文档链接} (v{x.y})
+- {Diff 链接}
+
+### 条件项关闭状态
+
+| 原条件项 | 状态 | 证据 |
+|---------|------|------|
+| {描述} | 已关闭 / 部分关闭 / 未关闭 | {链接} |
+
+### 请求重新评审
+
+请 {评审人} 重新评审。
+```
+
+### 2.4 完成评审 Comment 模板（Gate 通过结论）
+
+```markdown
+## 评审完成: {Gate 名称}
+
+**项目**: {project_id}
+**Issue**: #{N}
+**Gate**: {Gate 名称}
+**完成时间**: {YYYY-MM-DD HH:MM}
+**决策人**: {角色列表}
+
+### 结论
+
+`Approved` — 允许进入下游阶段
+
+### 签字
+
+| 角色 | 签字人 | 时间 |
+|------|--------|------|
+| {角色 1} | {Name} | {时间} |
+| {角色 2} | {Name} | {时间} |
+| {角色 3} | {Name} | {时间} |
+
+### 证据链接
+
+- {文档链接}
+- {评审记录链接}
+
+### 下一节点
+
+{下游阶段名称}
+
+### 产物关联表
+
+| 产物类型 | 链接 | 版本 |
+|---------|------|------|
+| PRD | {链接} | v{x.y} |
+| Tech | {链接} | v{x.y} |
+```
+
+### 2.5 Human Review 发起 Comment 模板
+
+```markdown
+## Human Review 发起
+
+**项目**: {project_id}
+**Issue**: #{N}
+**HR 阶段**: Human Review #1 / Human Review #2
+**发起时间**: {YYYY-MM-DD HH:MM}
+**发起人**: PM
+
+### 评审对象
+
+- **PR 链接**: {PR URL}
+- **PR 类型**: 文档 PR (doc-{issue}) / 代码 PR (feature-{issue})
+
+### 核心内容概括
+
+{用 3-5 句话概括本次交付的核心内容，不要粘贴全文}
+
+### 前置条件检查
+
+- [ ] PRD 已完成并签字
+- [ ] Tech Spec 已完成并签字
+- [ ] QA Case Design 已完成并签字（HR#1）
+- [ ] 测试报告已完成并签字（HR#2）
+- [ ] 文档 PR 已合并（HR#2 前置）
+
+### 评审重点
+
+{Human 应重点关注的 2-3 个核心问题}
+
+### 期望完成时间
+
+{YYYY-MM-DD}
+
+---
+请 Human 在此 comment 下方回复评审结论。
+```
+
+---
+
+## 3. 文档 vs Comment 边界规则
+
+### 3.1 必须在独立文档中的内容（严禁 Comment 替代）
+
+| 内容类型 | 文档位置 | 原因 |
+|---------|---------|------|
+| PRD | `docs/prd/PRD-{issue}_v*.md` | 正式交付物，需版本化、可追溯 |
+| Tech Spec | `docs/tech/Tech-{issue}_v*.md` | 正式交付物，需版本化、可追溯 |
+| QA Case Design | `docs/qa/QA-Case-{issue}_v*.md` | 正式交付物，需版本化、可追溯 |
+| **QA 测试报告** | `docs/qa/qa-report-{issue}_v*.md` | **正式交付物，Issue #19 违规点** |
+| 发布记录 | `docs/release/release-{issue}_v*.md` | 正式交付物，需版本化、可追溯 |
+| 审计报告 | `docs/pmo/issues/` 或 `docs/pmo/resolutions/` | 正式治理记录 |
+| 会议纪要 | `docs/memo/` | 正式会议记录 |
+
+### 3.2 可以在 Comment 中的内容
+
+| 内容类型 | 位置 | 原因 |
+|---------|------|------|
+| 评审结论 | Issue Comment | 流程 Gate 留痕，结构化摘要 |
+| 评审意见 | Issue Comment | 流程 Gate 留痕，结构化摘要 |
+| 迭代说明 | Issue Comment | 流程 Gate 留痕，指向文档变更 |
+| 完成确认 | Issue Comment | 流程 Gate 留痕，签字记录 |
+| HR 发起 | Issue Comment | 流程 Gate 留痕，概括核心内容 |
+| 进度更新 | Issue Comment | 状态同步 |
+| 关闭请求 | Issue Comment | 流程 Gate 留痕 |
+
+### 3.3 "严禁 Comment 替代文档"判定标准
+
+**触发条件（满足任一即判定为违规）**：
+
+1. Comment 中包含超过 500 字的结构化设计内容（如 PRD 正文、Tech Spec 正文、Case Design 正文）
+2. Comment 中包含测试用例的完整详细描述（而非摘要和链接）
+3. Comment 中包含测试执行结果的完整数据（而非摘要和链接）
+4. Comment 被当作唯一交付物，没有对应的独立文档文件
+5. Comment 中包含版本历史、变更记录等应存在于文档中的元数据
+
+**正确做法**：
+
+- Comment = 结构化结论 + 链接摘要 + 签字记录
+- 文档 = 完整正文 + 版本历史 + 详细设计 + 完整数据
+- Comment 必须引用文档链接，不得复制文档正文
+
+### 3.4 Issue #19 违规分析
+
+| 违规项 | 实际情况 | 正确做法 |
+|--------|---------|---------|
+| QA 测试报告仅以 comment 发布 | QA 测试报告内容写在 Issue comment 中 | 必须先创建 `docs/qa/qa-report-019_v*.md`，再在 comment 中发布摘要+链接 |
+| 无独立 QA 报告文档 | 未找到 `docs/qa/qa-report-019_*.md` | 必须创建独立文档 |
+
+---
+
+## 4. 修改计划
+
+### 4.1 需要修改的 prompts/*.md
+
+| 文档 | 修改内容 | 优先级 |
+|------|---------|--------|
+| `002_develop_pipeline.md` | 1. 在"Issue Comment 强制要求"章节追加 comment 类型定义<br>2. 追加"严禁 comment 替代文档"规则<br>3. 追加 comment 链路完整性检查规则 | P0 |
+| `013_github_issue_and_review_comments.md` | 1. 追加 5 种 comment 类型定义<br>2. 追加文档/comment 边界规则<br>3. 追加 comment 链路定义（发起→评审→迭代→完成） | P0 |
+| `017_human_review_and_signoff.md` | 1. 追加 HR 发起 comment 规范<br>2. 追加 HR 发起模板引用 | P0 |
+| `014_process_compliance_and_audit.md` | 1. 追加"comment 替代文档"检查项<br>2. 追加 comment 链路完整性审计项 | P1 |
+| `020_issue_comment_gate_and_artifact_linkage.md` | 1. 追加 comment 类型与产物关联映射<br>2. 追加链路完整性检查 | P1 |
+
+### 4.2 需要修改的 skills/*.md
+
+| 文档 | 修改内容 | 优先级 |
+|------|---------|--------|
+| `skills/product-manager/SKILL.md` | 1. 在"输出格式"章节追加 comment 类型引用<br>2. 明确 PM 需使用对应 comment 模板 | P1 |
+| `skills/qa-engineer/SKILL.md` | 1. 强化"QA 测试报告必须是独立文档"规则<br>2. 明确"comment 中只放摘要+链接，正文在文档中" | P0 |
+| `skills/pmo/SKILL.md` | 1. 在"合规检查对象"中追加 comment 链路完整性检查<br>2. 追加"comment 替代文档"检查项 | P1 |
+| `skills/workflows/tech-review.md` | 1. 明确各步骤应使用的 comment 类型 | P2 |
+| `skills/workflows/qa-validation.md` | 1. 明确"QA 报告必须先创建独立文档"<br>2. 明确 comment 中只放摘要 | P0 |
+| `skills/workflows/human-review.md` | 1. 追加 HR 发起 comment 规范<br>2. 明确发起→评审→完成的 comment 链路 | P0 |
+| `skills/workflows/prd-review.md` | 1. 明确各步骤应使用的 comment 类型 | P2 |
+
+### 4.3 需要新建/修改的模板
+
+| 文档 | 操作 | 内容 | 优先级 |
+|------|------|------|--------|
+| `skills/templates/review-comment-template.md` | 重写 | 包含 5 种 comment 类型模板 | P0 |
+| `skills/templates/qa-report-template.md` | 无需修改 | 现有模板已足够，需强化引用 | P1 |
+
+### 4.4 需要回溯的 Issue
+
+| Issue | 回溯动作 | 责任人 |
+|-------|---------|--------|
+| #19 | 补充独立 QA 报告文档 `docs/qa/qa-report-019_v*.md` | QA |
+
+---
+
+## 5. 执行顺序
+
+```
+Step 1: 新建/重写 review-comment-template.md（5 种模板）
+        ↓
+Step 2: 修改 002_develop_pipeline.md（追加 comment 规范和边界规则）
+        ↓
+Step 3: 修改 013_github_issue_and_review_comments.md（追加类型和链路）
+        ↓
+Step 4: 修改 017_human_review_and_signoff.md（追加 HR 发起规范）
+        ↓
+Step 5: 修改 skills/qa-engineer/SKILL.md（强化 QA 报告文档规则）
+        ↓
+Step 6: 修改 skills/workflows/human-review.md（追加发起规范）
+        ↓
+Step 7: 修改 skills/workflows/qa-validation.md（强化文档边界）
+        ↓
+Step 8: 回溯 Issue #19（补充 QA 报告文档）
+        ↓
+Step 9: 修改 skills/pmo/SKILL.md（追加审计项）
+        ↓
+Step 10: 修改其他 skills/workflows/*.md（明确 comment 类型）
+```
+
+---
+
+## 6. 验收标准
+
+- [ ] `skills/templates/review-comment-template.md` 包含 5 种 comment 类型完整模板
+- [ ] `002_develop_pipeline.md` 包含"严禁 comment 替代文档"规则
+- [ ] `013_github_issue_and_review_comments.md` 包含 comment 链路定义
+- [ ] `017_human_review_and_signoff.md` 包含 HR 发起 comment 规范
+- [ ] `skills/qa-engineer/SKILL.md` 明确"QA 报告必须是独立文档"
+- [ ] Issue #19 已补充独立 QA 报告文档
+- [ ] 所有修改通过 PR 合并（Refs #33）