openharmonyinsight/ohos-req-review-gate

OHOS Review Ready Gate (结构化判定)

Announce at start: "我正在使用 ohos-req-review-gate skill 对 04-feature.md 执行 Review Ready Gate。"

定位

OHOS Review Ready Gate 是 Phase 0 唯一的独立 subagent 结构化判定——主 session 已持有 01-04 全文上下文，自行推算 Gate 会产生确认偏差，必须由隔离上下文的 subagent 执行判定。Gate JSON 输出的 observations 字段（PIR #152 P1）将性能/功耗/内存等需 Phase 5-7 实测的指标归类为观测项，不阻塞 Ready 判定，在 Phase 1-9 跟踪闭环。

适用边界

• ✅ 适用：Phase 0 Step 0.5（Feature 评审就绪）
• ❌ 不适用：决策 0（立项评审）、决策 1（方案确认）、决策 1.5（SIG 评审）、决策 2（Phase 4 评审）、决策 3（代码审查）、Phase 5 Step 5.2（设计待解决问题门禁）——这些由主 session / 后续 phase 流程承载
• 后续如果其他决策点也需要物化，可参考本 skill 的 JSON 输出契约复制推广

输入

• {docs_dir}/01-requirement.md
• {docs_dir}/02-feasibility.md
• {docs_dir}/03-arch-decision-record.md
• {docs_dir}/04-feature.md
• reference/feature-checklist.md（检查项判定规则与边缘情况处理的详细定义，必须在流程第1步加载读取）

04-feature.md 不存在时直接判定为 Not Ready，并返回错误说明（不试图推断）。

Gate 检查项（8 项固定 + 3 项结构一致性 + 1 项遗留问题闭环 = 12 项；条件项为独立字段）

8 项固定检查对应 feature.md §1-§5（拆分决策与工作量约束同属 §5）+ 技术方向（引用 03-arch-decision-record.md）+ 影响性分析（模板外补充章节），避免规则两套。3 项结构一致性检查为本 skill 新增，确保跨文档数据传播完整。1 项遗留问题闭环检查确保 03-arch-decision-record.md §6 由用户评审会议输入且闭环可追溯。逐项读取 04-feature.md 对应章节，按以下规则判定：

固定检查项（8 项）：

| 检查项 | 要求 | 判定方法 | |--------|------|----------| | 概述与价值 | 有核心诉求和业务价值描述 | §1 章节存在且非占位符 | | 范围明确 | 目标和非目标已列出 | §2 章节存在且非占位符 | | AC 完整 | 有可观察指标和验证方式 | §3 至少 1 条 AC 行非占位符 | | 受影响范围 | 明确跨仓模块、Owner/SIG | §4 至少 1 条影响范围行非占位符 | | 拆分决策 | 有拆分结论和 proposal 边界 | §5 章节存在且非占位符 | | 工作量约束 | 每个 proposal 不超过复杂度上限（简单≤5/标准≤8/复杂≤15 人月） | §5 每个 proposal 工作量不超过对应复杂度上限 | | 技术方向 | 有选定方案（引用 03-arch-decision-record.md） | 选定方案引用 03-arch-decision-record.md（feature 模板无对应章节） | | 影响性分析 | 5方影响类型已分析 | 影响性分析章节（模板外补充）5 行均非占位符 |

结构一致性检查项（3 项新增，仅做 Ready/Conditional/Not Ready 决策判定，不重复校验内容）：

职责边界： ohos-req-feature-baseline skill 在生成期做模块覆盖完整性/术语一致性的逐项校验和修复；本 skill 只做最终的 Ready/Conditional/Not Ready 决策判定，引用 feature skill 的校验结果（不重复执行校验逻辑）。条件项传播完整性为本 skill 独有（feature skill 不涉及 02/03 的条件项跨文档追溯）。

| 检查项 | 要求 | 判定方法 | |--------|------|----------| | 模块覆盖完整性 | 04 §4声明覆盖了所有涉及模块（引用 feature skill 校验结论） | 读取 04 §4"模块覆盖检查"结论字段；结论=pass→pass；结论=warn或缺失→warn（block_reasons: "模块覆盖检查未通过或未执行"） | | 影响类型术语一致性 | 04 §4影响类型标签无漂移（引用 feature skill 校验结论） | 读取 04 §4"术语一致性检查"结论字段；结论=pass→pass；结论=warn或缺失→warn | | 条件项传播完整性 | §5拆分前置条件覆盖 02 §6 和 03 §6 全部条件项 | 提取02/03中所有条件项编号，验证每个出现在04 §5；缺失→warn |

遗留问题闭环检查项（1 项新增）：

| 检查项 | 要求 | 判定方法 | |--------|------|----------| | 遗留问题闭环 | 03-arch-decision-record.md §6 遗留问题由用户评审会议输入且每条负责人/解决动作/计划关闭时间齐全 | 读取03 §6：①含占位标注[待用户评审会议后填写]→fail（block_reasons:"03-arch-decision-record.md §6遗留问题未由用户评审会议输入"）；②任一遗留项缺少负责人/解决动作/计划关闭时间→fail（block_reasons:"遗留项三字段不全"）；③无遗留项（用户认定无需遗留）或全部齐全→pass |

条件项检查（独立字段）：

• 04-feature.md 中所有标记为"⚠️"或"未通过/未知"的项必须都有 Owner 和关闭时点，否则提升为失败项

Phase 0 观测项（不阻塞 Gate 判定）：

部分条件项的关闭依赖于 Phase 5-7（实现+测试阶段）才能获取的量化数据（如性能基准测试结果、功耗实测数据、内存占用基线等）。这类条件项在 Phase 0 阶段客观上无法关闭，若将其作为 Gate 阻塞项，会导致 Gate 永远停留在 Conditional Ready、IR 永远 Conditional、handoff 永远 ConditionalReady。

分类规则：

| 条件项类型 | 判定依据 | Gate 影响 | 跟踪方式 | |-----------|---------|----------|---------| | Phase 0 可关闭条件项 | 所需信息在 Phase 0 范围内可获取（如 AC 缺验证方式、模块覆盖有排除理由等） | 缺 Owner/动作/时点 → 升级为 fail，阻塞 Gate | 条件项清单 | | Phase 0 观测项 | 关闭依赖 Phase 5-7 实测数据（性能基准、功耗实测、内存基线、稳定性测试等） | 不阻塞 Gate Ready/Not Ready 判定；Gate 结论按其他检查项判定 | 独立「Phase 0 观测项」字段，在 Phase 1-9 跟踪闭环 |

观测项识别规则：条件项描述中含"性能基准""功耗实测""内存占用基线""稳定性测试""压力测试"等需实际运行才能获取的量化指标时，自动归类为观测项。观测项仍需记录 Owner 和目标关闭时点（指向 Phase 5-7 对应阶段），但不影响 Gate 结论。

Gate 结论修订规则：

• Ready：无 fail，无可关闭 warn 项（观测项不计入 warn 统计）
• Conditional Ready：无 fail，有可关闭 warn 项且每条都有 Owner/动作/时点（观测项单独列出，不影响升级判定）
• Not Ready：有 fail，或有可关闭 warn 项但缺少 Owner/动作/时点

流程

1. 读取 reference/feature-checklist.md 获取各检查项的 Pass/Warn/Fail 判定规则与边缘情况处理规则；读取 04-feature.md（不存在 → 直接 Not Ready + 错误原因）。
2. 读取 §1-§5 及影响性分析补充章节的内容，只引用必要的摘要（不嵌入 01-04 全文）。
3. 对每项检查按上表规则判定 pass / warn / fail。
4. 收集所有 warn 项，按分类规则区分为「Phase 0 可关闭条件项」和「Phase 0 观测项」：
   • 可关闭条件项必须含 Owner、关闭动作、关闭时点，否则升级为 fail
   • 观测项记录 Owner 和目标关闭时点（指向 Phase 5-7），但不影响 Gate 判定
5. 汇总得到 Gate 结论（观测项不计入 warn 统计）：
   • Ready：无 fail，无可关闭 warn 项
   • Conditional Ready：无 fail，有可关闭 warn 项且每条都有 Owner/动作/时点
   • Not Ready：有 fail，或有可关闭 warn 项但缺少 Owner/动作/时点
6. 同时写两份产物：
   • tmp/decision_gate_{feature_id}_{timestamp}.json（机读）
   • tmp/decision_gate_{feature_id}_{timestamp}.md（人读摘要）
7. 回传主 session：路径 + 结论 + 失败/条件项计数。不复读 01-04 内容。

⭐ 思维准则

在执行 Gate 检查前，自问以下问题：

• Before evaluating each check item, ask yourself: am I reading the actual § content from 04-feature.md, or inferring from the section title?
• Before upgrading a warn to fail, ask yourself: does the warn item genuinely lack Owner/close_action/close_at, or did I fail to extract them?
• Before returning Not Ready, ask yourself: have I checked the degradation rules for missing 02/03, or am I blanket-failing all structural checks?

输出契约

JSON Schema（机读）

{
  "feature_id": "<FEAT-YYYYMMDD-NNN>",
  "checks": [ /* 12 项检查结果，含 8 固定 + 3 结构一致性 + 1 遗留问题闭环 */ ],
  "summary": {"pass": 11, "warn": 0, "fail": 0},
  "gate": "Conditional Ready",
  "block_reasons": []
}

（完整 JSON Schema 示例见 reference/gate-schema-example.json）

字段语义

• gate：仅取 "Ready" | "Conditional Ready" | "Not Ready"
• summary.pass / summary.warn / summary.fail：12 项检查的统计
• conditions：所有可关闭 warn 项 + 关闭信息（Owner/动作/时点），如 Owner/动作/时点缺失，由本 skill 自动从 warn 升级为 fail
• observations：Phase 0 观测项（性能/功耗/内存等需 Phase 5-7 实测的指标），记录 Owner 和目标关闭阶段，不阻塞 Gate 判定
• next_action：主 session 路由提示（如"生成 IR"、"阻塞回 Step 0.4 补全"、"阻塞：feature.md 不存在"）
• block_reasons：升级为 fail 的条件项描述（仅在 gate=Not Ready 时非空）

Markdown 摘要（人读）

（人读 Markdown 摘要模板见 reference/gate-summary-template.md）

与主 Session 的契约

主 session 在 Phase 0 Step 0.5 时：

1. spawn ohos-req-review-gate subagent，task 仅含 docs_dir 绝对路径（不嵌 01-04 全文）
2. 等待 subagent 回传路径
3. 读 tmp/decision_gate_*.json（≤100 行结构化数据，符合 Token 经济性规则）
4. 根据 gate 字段路由：
   - "Ready"           → spawn ohos-req-feature-to-ir
   - "Conditional Ready" → spawn ohos-req-feature-to-ir（task 中追加 conditions 摘要）
   - "Not Ready"       → 阻塞；如 block_reasons 非空，用其内容生成 AskUserQuestion

NEVER

• 禁止主 session 自行读 01-04 推算 Gate: 必须通过 spawn 独立 subagent 执行，本 skill 的 JSON 输出是唯一 Gate 结论（原因：主 session 已持有 01-04 全文上下文，自行推算会产生确认偏差，独立 subagent 判定是唯一可信结论）
• 禁止嵌入 01-04 全文到 task: task 仅含 docs_dir 绝对路径，不嵌入 01-04 全文（原因：嵌入全文会 fork 上下文，导致 subagent token 爆炸且无法隔离判断）
• 禁止复读产物全文到会话: 正式产物落盘+路径回传，不复读全文（原因：复读全文违背 Token 经济性规则，正式产物只需落盘+路径回传）
• 禁止在 Gate 输出 JSON 中添加 schema 外字段: schema_version 1.0 固定字段不可增删，主 session 仅消费 gate/conditions/block_reasons 字段
• 禁止在 04-feature.md 不存在时尝试从 01-03 推断 Gate 结论: 必须直接判定 Not Ready 并返回错误说明

错误处理

| 场景 | 行为 | |------|------| | 04-feature.md 不存在 | 返回 feature_md_exists: false、gate: "Not Ready"、block_reasons: ["04-feature.md 不存在，请先执行 ohos-req-feature-baseline"] | | 04-feature.md 存在但 8 项表格完全空白 | 视为 Not Ready，所有 8 项均记 fail | | 02/03 缺失但 04 存在 | 仅依据 04 判定 8 项固定检查；3 项结构一致性检查退化规则：02缺失时 module_coverage / term_consistency / condition_propagation 均判 warn；03缺失时 condition_propagation 判 warn + followup_closure 判 fail（block_reasons: "03-arch-decision-record.md 缺失，遗留问题闭环无法验证"）；02+03同时缺失时 4 项均判 warn/fail | | JSON 写入失败 | 回传错误，主 session 退化为人工 Gate |

自检

• [ ] 8 项检查与 feature.md §1-§5 + 技术方向/影响性分析完全对齐，无新增无删减
• [ ] 3 项结构一致性检查已执行（模块覆盖/术语一致性/条件项传播）
• [ ] 1 项遗留问题闭环检查已执行（03 §6 用户输入+三字段齐全）
• [ ] 条件项 Owner/动作/时点缺失时自动升级为 fail
• [ ] 性能/功耗/内存等需 Phase 5-7 实测的条件项已归类为「观测项」，不阻塞 Gate 判定
• [ ] JSON 字段与 schema_version 一致
• [ ] Markdown 摘要表行数 = 12（8固定+3结构+1遗留）
• [ ] 不嵌入 01-04 全文到 task
• [ ] 回传 ≤ 15 行

输出

• 路径：
  • tmp/decision_gate_{feature_id}_{timestamp}.json
  • tmp/decision_gate_{feature_id}_{timestamp}.md
• 回传：JSON 路径、Gate 结论、pass/warn/fail 计数、block_reasons 数量