arkweb-spec-review

name	arkweb-spec-review
description	ArkWeb Spec 文档评审。可作为独立 subagent 运行。检查文档完整性、一致性、可行性。触发词：评审设计文档、Spec review、检查设计文档、需求评审。

ArkWeb Spec 文档评审

Announce at start: "我正在使用 arkweb-spec-review skill 评审设计文档。"

运行模式

模式 A：Subagent 模式（推荐）

作为独立 subagent 被 arkweb-architect 调用时，设计文档和代码分析结果路径已在 task 描述中提供，直接执行评审。

输入格式（从 task 描述中解析）：

## 待评审文档
{DOCS_REPO}/docs/{date}-{feature}-requirement.md

## 代码分析结果（用于交叉验证）
{DOCS_REPO}/analysis/{date}-{feature}-analysis.md

## 参考资料（按需读取）
- ACE Engine 索引：{DOCS_REPO}/analysis/arkweb-ace-engine-analysis.md
- WebWebView 分析：{DOCS_REPO}/analysis/web-webview-analysis.md

输出： 评审报告 → 保存到指定路径 → 回复评审结果摘要

模式 B：交互模式

在主 session 中直接调用，评审完成后呈现给用户，用户决定是否修改。

模式 C：最小化检视流程（独立检视 + 修改闭环）

适用于已有设计文档，只需检视和修改的场景，跳过 brainstorm/code-analysis/design-doc 全链路。

触发词： 检视设计文档、review checklist、快速检视

流程：检视 → 修改 → 复审 → 提 PR

Step 1: 读取设计文档 + Checklist 模版
Step 2: 执行 Checklist 33 项检视（输出结果表）
Step 3: 有阻塞项？
  ├─ 否 → 输出"通过"，流程结束
  └─ 是 → 逐组修改设计文档
         ├─ 每组修改提交一个 PR
         ├─ 老板审批合并
         ├─ 合并后重新检视该组修改项
         └─ 全部通过 → 流程结束

与模式 A/B 的区别：

• 不执行完整评审维度检查（5 维度 31 项），仅做 Checklist 33 项检视
• 不依赖代码分析结果交叉验证
• 检视不通过时直接修改文档（而非打回 design-doc skill）
• 每组修改独立提 PR，合并后复审该组，不重跑全量检视

---

概述

对已生成的 ArkWeb 设计文档进行系统评审，确保完整性、一致性和技术可行性。

评审维度

1. 完整性检查（10 项）

• 需求描述覆盖所有功能点（FR）
• 非功能需求覆盖（NFR）：性能/安全/兼容性/可测试性
• 每个章节有实质内容（无空章节/占位符）
• 包含架构图（ASCII）
• 包含类图（ASCII）
• 包含时序图（ASCII）
• 接口设计有参数表和返回值说明
• 接口设计有示例代码
• 测试用例矩阵完整
• 全量设计待办清单完整

2. 一致性检查（6 项）

• 术语统一（全文中同一概念使用相同术语）
• 架构描述与类图一致
• 时序图与接口设计一致
• 设备差异表与兼容性分析一致
• 工期估算与方案复杂度匹配
• 文件路径与实际代码索引一致（交叉验证）

3. 技术可行性检查（5 项）

• 方案涉及的 ArkWeb API 是否已存在（查 ace_engine 分析文档）
• 涉及的 Chromium 内核修改是否有上游支持
• OHOS 平台 API 依赖是否在目标版本可用
• 性能基线是否可达成
• 兼容性降级方案是否合理

4. DFX 完整性（6 项）

• 可靠性设计（异常处理、重试、降级）
• 安全设计（权限、沙箱、数据保护）
• 可扩展性设计（接口预留、插件机制）
• 可配置性设计（开关、参数）
• 兼容性设计（版本兼容、向前/向后兼容）
• 可测试性设计（测试点、自动化方案）

5. 文档规范（4 项）

• 文件命名符合 {YYYY-MM-DD}-{feature-name}-requirement.md
• 关键决策点有 <!-- architect: ... --> 注释
• 1+8 设备差异表完整
• 工期估算合理

6. 接口设计规范（7 项 — 历史纠正项固化）

⚠️ 以下为多轮评审反复出现的问题，已固化为强制检查项：

• 说明列四段式结构： 参数表中每个字段的「说明」列必须包含描述/前置条件/规格/异常处理四段，内容过多时引用具体表格或章节。禁止在表格下方另起独立段落写四段式（与说明列冗余）。若参数表后有"接口整体规格"段落，仅保留跨字段的全局性说明（如执行语义、公共异常处理），不重复字段级信息。
• 设备差异表必须用表格： 即使所有设备均支持，也必须保留表格格式，每个格子填"支持"。禁止删除表格改为纯文字描述（如"不涉及。所有设备均支持"）。不支持的设备在对应格标注原因。
• 字段关联关系： 参数表后的字段关联关系说明必须存在（互斥/依赖/联动），不得缺失。
• 接口入参全文档联动： 当接口入参格式变更（如字段名、类型、结构变化），全文所有引用处必须同步更新，包括但不限于：功能范围表、典型场景示例、架构图 JSON 示例、类图成员变量、时序图、C++ 代码/伪代码、错误码触发场景、DFX 分析、设备矩阵功能点命名、全量特性表。不得残留旧字段名。
• 方案变更全文档联动： 当实现方案发生重大变更（如 JS 注入 → C++ DOM API），以下章节必须全部重写/更新：功能概述（实现路径描述）、架构图（内核层描述）、类图（方法命名）、时序图（NWebImpl→Chromium 的调用方式）、C++ 代码（核心 API 调用）、JS 注入模板（删除或改为降级方案）、框架兼容性（新方案的兼容性分析）、伪代码、接口规格汇总（描述中的实现方式）、DFX（安全设计检查等）、演进路线/降级方案。
• 错误码完整性： 错误码定义表的触发场景描述必须与实际实现方式匹配。方案变更后（如不再使用 JS 注入），需删除已不适用的错误码（如 ERROR_SETTER_NOT_AVAILABLE），新增方案特有的错误码（如 ERROR_CPP_API_NOT_AVAILABLE），并更新其他错误码的触发场景描述（如"document.evaluate()" → "Document::EvaluateXPath()"）。
• 术语一致性： 全文同一概念必须使用相同术语。方案变更后，旧术语（如 setValue/selectOption/ExecuteJavaScript）不得残留，C++ 类成员变量名（如 eventType_）除外。

需求检视 Checklist

评审流程中嵌入结构化检视环节，使用通用 Checklist 模版（assets/templates/requirement-design-review-checklist.md）逐项检查设计文档质量。 Checklist 为设计文档评审的质量门禁：检视不通过时，要求 design-doc 修改后重新评审。

Checklist 分类

• 必选（27 项）： 大部分设计文档需要满足，少量不涉及的可填写不涉及
• 可选（6 项）： 设计文档中写明不涉及即通过，如涉及则需评审满足度

检视时机

在 Step 2 逐项检查完成后、Step 3 输出报告前执行。

检视不通过的处理

• 🔴 必选项不满足 → 打回 design-doc 修改，修改后重新走 spec-review
• ⚠️ 可选项涉及但不满足 → 建议修改，不阻塞
• ❌ 必选项不涉及 → 需在说明列给出不涉及理由

Checklist 模版路径

assets/templates/requirement-design-review-checklist.md

8 大类 33 项：需求分析(5) / 需求规格(3) / KPI&KQI(4) / 模块(3) / 接口(2) / 设计(8) / 可测试性(3) / 安全(5)

---

流程

Step 1: 读取文档

读取待评审文档 + 代码分析结果（用于交叉验证类名、接口签名、文件路径）。

Step 2: 逐项检查

按上述 5 个维度逐项检查，记录问题。

交叉验证要点：

• 设计文档中的类名是否在 ace_engine 分析中存在
• 接口签名是否与 web_webview 分析中的定义一致
• 文件路径是否正确

Step 2.5: Checklist 结构化检视

基于 assets/templates/requirement-design-review-checklist.md 逐项检查，输出 Checklist 结果表：

## Checklist 检视结果

| # | 检查项 | 必/可选 | 状态 | 说明 |
|---|--------|---------|------|------|
| 1 | ... | 必选 | ✅/⚠️/❌ | ... |
| ... | ... | ... | ... | ... |

### 检视统计
- 必选满足：N / 27
- 必选不满足：N（阻塞项）
- 必选不涉及：N
- 可选涉及：N / 6
- 可选不涉及：N

### 检视结论
✅ 通过 / ❌ 不通过（N 项必选阻塞）

判定规则：

• 必选无"不满足"项 → ✅ 通过，进入 Step 3
• 必选有"不满足"项 → ❌ 不通过，输出评审报告后打回 design-doc 修改

Step 3: 输出评审报告

# {文档名} 评审报告

## 评审结果：{通过 / 需修改 / 不通过}

## Checklist 检视结果

| # | 检查项 | 必/可选 | 状态 | 说明 |
|---|--------|---------|------|------|
| 1 | ... | 必选 | ✅/⚠️/❌ | ... |

### 检视统计
- 必选满足：N / 27 | 必选不满足：N | 必选不涉及：N
- 可选涉及：N / 6 | 可选不涉及：N
- 检视结论：✅ 通过 / ❌ 不通过

## 问题清单
### 🔴 必须修改（含 Checklist 必选不满足项）
1. [描述] - 位置：{章节} - 来源：Checklist #N

### 🟡 建议修改
1. [描述] - 位置：{章节}

### 🟢 优秀实践
1. [描述]

## 统计
- Checklist 总检查项：33（必选 27 / 可选 6）
- Checklist 满足：N | 不满足：N | 不涉及：N
- 评审维度检查项：N
- 通过：N
- 🔴 必须修改：N 项
- 🟡 建议修改：N 项
- 🟢 优秀实践：N 项

Step 4: 闭环处理

Checklist 不通过时（必选有阻塞项）

• 输出评审报告，明确列出 Checklist 不满足项
• 打回 arkweb-design-doc 修改
• 修改后重新走 spec-review 流程

Checklist 通过但评审维度有问题时

• 🔴 必须修改项：打回 design-doc 修改
• 🟡 建议修改项：不阻塞，记录在评审报告中

全部通过时

• 进入下一阶段（create-sr）

Step 5: 输出

Subagent 模式

保存评审报告并回复结果摘要。不执行修改（由主 session 的决策 3 处理）。

交互模式

呈现评审结果，用户决定是否修改。修改后可重新评审。

产出物

• 路径：{DOCS_REPO}/docs/YYYY-MM-DD-{feature-name}-review.md

Subagent 回复格式

✅ spec-review 完成
📄 报告：{file_path}
📊 评审结果：{通过 / 需修改 / 不通过}
📋 Checklist 检视：满足 N/33 | 不满足 N | 不涉及 N（必选阻塞 N）
- 总检查项：{N}，通过：{N}
- 🔴 必须修改：{N} 项
- 🟡 建议修改：{N} 项
- 🟢 优秀实践：{N} 项