parallel-review-implementation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Parallel Review Implementation

并行实现评审

Receive a work package diff as read-only input and produce structured findings conforming to

review-findings.schema.json

. Designed for vendor-diverse dispatch — runs independently per package.

接收工作包diff作为只读输入，生成符合

review-findings.schema.json

规范的结构化评审结果。设计支持多供应商调度——每个包独立运行。

Arguments

参数

$ARGUMENTS

<change-id> <package-id>

(e.g., "add-user-auth wp-backend")

$ARGUMENTS

<change-id> <package-id>

（例如："add-user-auth wp-backend"）

Prerequisites

前置条件

Work package implementation is complete
Package worktree has committed changes
Work-queue result JSON is available

工作包实现已完成
包工作树已提交所有变更
工作队列结果JSON已就绪

Input (Read-Only)

输入（只读）

The reviewer receives per-package context:

Package definition from
```
work-packages.yaml
```
(scope, locks, verification)
Contract artifacts from
```
contracts/
```
relevant to this package
Git diff of all files modified by this package (
```
git diff <base>...<head>
```
)
Work-queue result JSON (verification results, files_modified, escalations)
Spec requirements traced to this package via
```
tasks.md
```

The reviewer MUST NOT modify any files.

评审者接收每个包的上下文信息：

包定义来自
```
work-packages.yaml
```
（范围、锁、验证规则）
契约产物来自
```
contracts/
```
目录下与该包相关的文件
Git diff包含该包修改的所有文件（
```
git diff <base>...<head>
```
）
工作队列结果JSON（验证结果、修改文件列表、升级事项）
需求规范通过
```
tasks.md
```
关联到该包

评审者严禁修改任何文件。

Steps

步骤

1. Load Review Context

1. 加载评审上下文

Parse the package-id argument and load:

Read
```
work-packages.yaml
```
and extract the target package definition
Read relevant contract artifacts (OpenAPI, DB schema, event schemas)
Read the git diff for this package's worktree
Read the work-queue result JSON (if available)
Read traced requirements from
```
specs/**/spec.md
```

解析package-id参数并加载以下内容：

读取
```
work-packages.yaml
```
并提取目标包的定义
读取相关的契约产物（OpenAPI、DB schema、事件schema）
读取该包工作树的git diff
读取工作队列结果JSON（若存在）
从
```
specs/**/spec.md
```
读取关联的需求规范

2. Scope Verification

2. 范围校验

Before reviewing code quality, verify scope compliance:

All modified files are within the package's
```
write_allow
```
globs
No modified files match
```
deny
```
globs
Lock keys match the package's declared locks

If scope violations are found, emit a

correctness

finding with

critical

criticality.

在评审代码质量前，先校验范围合规性：

所有修改的文件都在包的
```
write_allow
```
通配符路径范围内
没有修改的文件匹配
```
deny
```
通配符路径
锁密钥与包声明的锁匹配

如果发现范围违规，输出严重级别为

critical

的

correctness

类型评审结果。

3. Contract Compliance Review

3. 契约合规评审

Check that the implementation matches declared contracts:

API endpoints match OpenAPI path/method/response schemas
Database queries use only declared tables and columns
Event payloads match event contract schemas
Error responses follow the specified format (e.g., RFC 7807)

检查实现是否与声明的契约匹配：

API端点与OpenAPI的路径/方法/响应schema匹配
数据库查询仅使用声明的表和列
事件负载与事件契约schema匹配
错误响应遵循指定格式（例如：RFC 7807）

For Backend Packages

针对后端包

All OpenAPI-declared endpoints are implemented
Request validation matches schema constraints
Response serialization matches declared types

所有OpenAPI声明的端点都已实现
请求校验与schema约束匹配
响应序列化与声明的类型匹配

For Frontend Packages

针对前端包

API calls use generated TypeScript types
Error handling covers all declared error responses
Events are consumed with correct schema

API调用使用生成的TypeScript类型
错误处理覆盖所有声明的错误响应
事件消费使用正确的schema

4. Code Quality Review

4. 代码质量评审

5. Verification Result Cross-Check

5. 验证结果交叉校验

If work-queue result is available:

```
verification.passed
```
is consistent with step results
Test count is reasonable for the scope of changes
No escalations are unaddressed

如果工作队列结果可用：

```
verification.passed
```
与步骤结果一致
测试数量与变更范围匹配合理
无未处理的升级事项

6. Produce Findings

6. 生成评审结果

Generate findings as JSON conforming to

review-findings.schema.json

json

{
  "review_type": "implementation",
  "target": "<package-id>",
  "reviewer_vendor": "<model-name>",
  "findings": [
    {
      "id": 1,
      "type": "contract_mismatch",
      "criticality": "high",
      "description": "POST /v1/users returns 200 but OpenAPI spec declares 201",
      "resolution": "Change response status code to 201 Created",
      "disposition": "fix",
      "package_id": "wp-backend"
    }
  ]
}

生成符合

review-findings.schema.json

规范的JSON格式评审结果：

json

{
  "review_type": "implementation",
  "target": "<package-id>",
  "reviewer_vendor": "<model-name>",
  "findings": [
    {
      "id": 1,
      "type": "contract_mismatch",
      "criticality": "high",
      "description": "POST /v1/users returns 200 but OpenAPI spec declares 201",
      "resolution": "Change response status code to 201 Created",
      "disposition": "fix",
      "package_id": "wp-backend"
    }
  ]
}

Finding Types

评审结果类型

```
spec_gap
```
— Implementation misses a spec requirement
```
contract_mismatch
```
— Code doesn't match contract (OpenAPI, DB schema, events)
```
architecture
```
— Structural concern or pattern violation
```
security
```
— Security vulnerability
```
performance
```
— Performance concern
```
style
```
— Code style or convention issue
```
correctness
```
— Bug or logical error

```
spec_gap
```
— 实现遗漏了规范需求
```
contract_mismatch
```
— 代码与契约不匹配（OpenAPI、DB schema、事件）
```
architecture
```
— 结构问题或模式违规
```
security
```
— 安全漏洞
```
performance
```
— 性能问题
```
style
```
— 代码风格或规范问题
```
correctness
```
— Bug或逻辑错误

Dispositions

处理建议

```
fix
```
— Must fix before integration merge
```
regenerate
```
— Contract needs updating (triggers escalation)
```
accept
```
— Minor issue, acceptable as-is
```
escalate
```
— Requires orchestrator decision (scope violation, contract revision)

```
fix
```
— 集成合并前必须修复
```
regenerate
```
— 契约需要更新（触发升级）
```
accept
```
— 小问题，当前状态可接受
```
escalate
```
— 需要协调者决策（范围违规、契约修订）

7. Validate Output

7. 校验输出

bash

python3 -c "
import json, jsonschema
schema = json.load(open('openspec/schemas/review-findings.schema.json'))
findings = json.load(open('<findings-output-path>'))
jsonschema.validate(findings, schema)
print('Valid')
"

bash

python3 -c "
import json, jsonschema
schema = json.load(open('openspec/schemas/review-findings.schema.json'))
findings = json.load(open('<findings-output-path>'))
jsonschema.validate(findings, schema)
print('Valid')
"

8. Submit Findings

8. 提交评审结果

Write findings to

artifacts/<package-id>/review-findings.json

If any finding has

disposition: "escalate"

disposition: "regenerate"

, the orchestrator will handle escalation (pause-lock, contract revision bump, etc.).

将评审结果写入

artifacts/<package-id>/review-findings.json

。

如果任何评审结果的

disposition

为

"escalate"

或

"regenerate"

，协调者将处理升级流程（暂停锁、契约版本升级等）。

Output

输出

artifacts/<package-id>/review-findings.json

conforming to

review-findings.schema.json

符合

review-findings.schema.json

规范的

artifacts/<package-id>/review-findings.json

文件

Orchestrator Integration

协调者集成

The orchestrator dispatches this skill once per completed work package:

Package completes → work-queue result submitted
Orchestrator validates result (schema, scope, verification)
Orchestrator dispatches review skill with package context
Review findings feed into integration gate decision

Integration Gate Logic (orchestrator-side):

All packages reviewed with no
```
fix
```
or
```
escalate
```
findings → proceed to integration
Any
```
fix
```
finding → return to package agent for remediation
Any
```
escalate
```
finding → trigger escalation protocol

协调者为每个完成的工作包调度一次该技能：

包完成 → 提交工作队列结果
协调者校验结果（schema、范围、验证）
协调者传入包上下文调度评审技能
评审结果作为集成门禁的决策依据

集成门禁逻辑（协调者侧）：

所有包评审完成，无
```
fix
```
或
```
escalate
```
类型结果 → 进入集成流程
存在任何
```
fix
```
结果 → 返回给包Agent进行修复
存在任何
```
escalate
```
结果 → 触发升级协议

Design for Vendor Diversity

多供应商适配设计

parallel-review-plan

, this skill is self-contained:

No coordinator dependencies required for execution
All input is file-based (read-only)
Output is a single JSON file with a well-defined schema
No side effects
Can be dispatched to any LLM vendor for independent review

与

parallel-review-plan

类似，该技能是自包含的：

执行无需协调器依赖
所有输入基于文件（只读）
输出为单个明确定义schema的JSON文件
无副作用
可调度给任意LLM供应商进行独立评审