diff --git "a/prompts/discuss/033_2026-04-23_comment\350\247\204\350\214\203\344\270\216\346\226\207\346\241\243\350\276\271\347\225\214\346\262\273\347\220\206\350\277\255\344\273\243\350\256\241\345\210\222.md" "b/prompts/discuss/033_2026-04-23_comment\350\247\204\350\214\203\344\270\216\346\226\207\346\241\243\350\276\271\347\225\214\346\262\273\347\220\206\350\277\255\344\273\243\350\256\241\345\210\222.md" new file mode 100644 index 0000000..de030ae --- /dev/null +++ "b/prompts/discuss/033_2026-04-23_comment\350\247\204\350\214\203\344\270\216\346\226\207\346\241\243\350\276\271\347\225\214\346\262\273\347\220\206\350\277\255\344\273\243\350\256\241\345\210\222.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 类型定义
2. 追加"严禁 comment 替代文档"规则
3. 追加 comment 链路完整性检查规则 | P0 | +| `013_github_issue_and_review_comments.md` | 1. 追加 5 种 comment 类型定义
2. 追加文档/comment 边界规则
3. 追加 comment 链路定义（发起→评审→迭代→完成） | P0 | +| `017_human_review_and_signoff.md` | 1. 追加 HR 发起 comment 规范
2. 追加 HR 发起模板引用 | P0 | +| `014_process_compliance_and_audit.md` | 1. 追加"comment 替代文档"检查项
2. 追加 comment 链路完整性审计项 | P1 | +| `020_issue_comment_gate_and_artifact_linkage.md` | 1. 追加 comment 类型与产物关联映射
2. 追加链路完整性检查 | P1 | + +### 4.2 需要修改的 skills/*.md + +| 文档 | 修改内容 | 优先级 | +|------|---------|--------| +| `skills/product-manager/SKILL.md` | 1. 在"输出格式"章节追加 comment 类型引用
2. 明确 PM 需使用对应 comment 模板 | P1 | +| `skills/qa-engineer/SKILL.md` | 1. 强化"QA 测试报告必须是独立文档"规则
2. 明确"comment 中只放摘要+链接，正文在文档中" | P0 | +| `skills/pmo/SKILL.md` | 1. 在"合规检查对象"中追加 comment 链路完整性检查
2. 追加"comment 替代文档"检查项 | P1 | +| `skills/workflows/tech-review.md` | 1. 明确各步骤应使用的 comment 类型 | P2 | +| `skills/workflows/qa-validation.md` | 1. 明确"QA 报告必须先创建独立文档"
2. 明确 comment 中只放摘要 | P0 | +| `skills/workflows/human-review.md` | 1. 追加 HR 发起 comment 规范
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）