review-quality

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Quality Review (Unified)

统一质量评审

Goal: turn “is this change good?” into a repeatable review with a clear merge/production readiness verdict.

This skill intentionally merges three review lenses:

Merge readiness (requirements alignment + risk + verification)
Code maintainability (Clean Code-style review)
Documentation consistency (README/docs vs implementation)

This is the single entry point for Ship Faster reviews. It includes an internal auto-triage:

Always run the unified review (this skill).
If React/Next.js performance risk is detected, also run
```
review-react-best-practices
```
and include its findings.
If UI surface changes are detected, also run a Web Interface Guidelines audit (a11y/focus/forms/motion/content overflow) and include terse
```
file:line
```
findings.

目标：将「此次变更是否合格？」转化为可重复的评审流程，并给出明确的合并/生产就绪性判定。

本技能特意整合了三个评审维度：

合并就绪性（需求对齐 + 风险 + 验证）
代码可维护性（Clean Code风格评审）
文档一致性（README/文档与实现的匹配度）

这是Ship Faster评审的唯一入口，内置自动分流机制：

始终运行统一评审（即本技能）。
若检测到React/Next.js性能风险，同时运行
```
review-react-best-practices
```
并纳入其评审结果。
若检测到UI层面变更，同时执行Web界面规范审计（无障碍/焦点/表单/动效/内容溢出），并以简洁的
```
file:line
```
格式呈现结果。

Inputs (recommended)

BASE_SHA=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master) HEAD_SHA=$(git rev-parse HEAD)

git diff --stat "$BASE_SHA..$HEAD_SHA" git diff "$BASE_SHA..$HEAD_SHA"

undefined

Process

流程

0) Auto-triage (Built-in Router)

0) 自动分流（内置路由）

Goal: reduce user choice. The reviewer decides which specialized review lens to apply, deterministically, based on the diff.

Collect signals (minimum):

bash

git diff --name-only "$BASE_SHA..$HEAD_SHA"
git diff --stat "$BASE_SHA..$HEAD_SHA"
git diff "$BASE_SHA..$HEAD_SHA"

Routing rules (apply in order):

Docs-only change (fast path):
- If every changed file is in
```
docs/**
```
  or ends with
```
.md|.txt|.rst
```
- Then run the unified review, but focus on Docs ↔ Code consistency + release risk (skip deep code maintainability unless docs reference code changes).
React/Next.js performance-sensitive change:
- If any changed file matches:
  - ```
  **/*.tsx
```
  ,
```
  **/*.jsx
```
- ```
next.config.*
```
    ,
```
app/**
```
    ,
```
pages/**
```
    ,
```
src/app/**
```
    ,
```
src/pages/**
```
  - React/Next entrypoints (
```
layout.tsx
```
    ,
```
page.tsx
```
    ,
```
middleware.ts
```
    ,
```
route.ts
```
    ,
```
loading.tsx
```
    )
- Or the diff contains performance-sensitive keywords (spot check via
```
git diff
```
  ):
  - ```
  use client
```
  ,
```
  Suspense
```
  ,
```
  dynamic(
```
  ,
```
  next/dynamic
```
  ,
```
  next/navigation
```
  ,
```
  React.cache
```
  ,
```
  revalidate
```
  ,
```
  fetch(
```
  ,
```
  headers()
```
  ,
```
  cookies()
```
- Then: run
```
review-react-best-practices
```
  and include its output (or link to its artifact) in the final report.
UI Web Interface Guidelines audit (a11y/UX rules, terse output):
- If any changed file matches:
  - UI code:
```
**/*.tsx
```
    ,
```
**/*.jsx
```
    ,
```
**/*.vue
```
    ,
```
**/*.html
```
    ,
```
**/*.css
```
    ,
```
**/*.scss
```
  - Common UI dirs:
```
app/**
```
    ,
```
pages/**
```
    ,
```
src/app/**
```
    ,
```
src/pages/**
```
    ,
```
components/**
```
    ,
```
src/components/**
```
- Then: fetch the latest Web Interface Guidelines and audit only the changed UI files first.
  - Source:
```
https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
```
  - Fetch method: WebFetch (if available) or
```
curl -fsSL <url>
```
- Output findings in terse
  file:line
  format, grouped by file (high signal, low prose). Treat a11y + focus issues as higher severity than cosmetic issues.

Output requirement (at top of your report):

undefined

目标：减少用户选择成本。评审器会根据代码差异，确定性地选择适用的专业评审维度。

收集信号（最低要求）：

bash

git diff --name-only "$BASE_SHA..$HEAD_SHA"
git diff --stat "$BASE_SHA..$HEAD_SHA"
git diff "$BASE_SHA..$HEAD_SHA"

路由规则（按顺序执行）：

仅文档变更（快速路径）：
- 若所有变更文件均位于
```
docs/**
```
  目录下，或后缀为
```
.md|.txt|.rst
```
- 则运行统一评审，但重点关注文档与代码一致性 + 发布风险（除非文档提及代码变更，否则跳过深度代码可维护性检查）。
React/Next.js性能敏感型变更：
- 若任一变更文件匹配以下规则：
  - ```
  **/*.tsx
```
  、
```
  **/*.jsx
```
- ```
next.config.*
```
    、
```
app/**
```
    、
```
pages/**
```
    、
```
src/app/**
```
    、
```
src/pages/**
```
  - React/Next入口文件（
```
layout.tsx
```
    、
```
page.tsx
```
    、
```
middleware.ts
```
    、
```
route.ts
```
    、
```
loading.tsx
```
    ）
- 或代码差异中包含性能敏感关键词（通过
```
git diff
```
  抽查）：
  - ```
  use client
```
  、
```
  Suspense
```
  、
```
  dynamic(
```
  、
```
  next/dynamic
```
  、
```
  next/navigation
```
  、
```
  React.cache
```
  、
```
  revalidate
```
  、
```
  fetch(
```
  、
```
  headers()
```
  、
```
  cookies()
```
- 则：运行
```
review-react-best-practices
```
  并将其输出（或其产物链接）纳入最终报告。
UI Web界面规范审计（无障碍/UX规则，简洁输出）：
- 若任一变更文件匹配以下规则：
  - UI代码：
```
**/*.tsx
```
    、
```
**/*.jsx
```
    、
```
**/*.vue
```
    、
```
**/*.html
```
    、
```
**/*.css
```
    、
```
**/*.scss
```
  - 常见UI目录：
```
app/**
```
    、
```
pages/**
```
    、
```
src/app/**
```
    、
```
src/pages/**
```
    、
```
components/**
```
    、
```
src/components/**
```
- 则：获取最新Web界面规范，优先审计变更的UI文件。
  - 来源：
```
https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
```
  - 获取方式：WebFetch（若可用）或
```
curl -fsSL <url>
```
- 以简洁的
  file:line
  格式输出结果，按文件分组（高信号、低冗余）。将无障碍与焦点问题视为比外观问题更严重的级别。

输出要求（置于报告顶部）：

undefined

Triage

分流结果

Docs-only: yes|no
React/Next perf review: yes|no
UI guidelines audit: yes|no
Reason: <1-3 bullets based on file paths / patterns>

undefined

仅文档变更：是|否
React/Next性能评审：是|否
UI规范审计：是|否
原因：<基于文件路径/模式的1-3条要点>

undefined

1) Merge readiness (verdict review)

1) 合并就绪性（判定评审）

Use the template:

references/code-reviewer.md

Minimum checks:

Requirements alignment (acceptance criteria hit, non-goals respected)
Side effects are gated (deploy/payments/DB writes require explicit approval)
Error handling is explicit (no silent failures)
Verification evidence exists (tests/build/typecheck/lint/manual steps)

使用模板：

references/code-reviewer.md

。

最低检查项：

需求对齐（满足验收标准，遵守非目标范围）
副作用已受控（部署/支付/数据库写入需明确审批）
错误处理明确（无静默失败）
存在验证证据（测试/构建/类型检查/代码扫描/手动步骤）

2) Clean Code maintainability scan

2) Clean Code可维护性扫描

Review the diff (and nearby touched code) across these dimensions:

Meaningful naming (avoid
```
data1
```
,
```
tmp
```
, mixed naming for same concept)
Small functions / SRP (very long functions, too many params, mixed responsibilities)
Duplication (DRY) (copy/paste logic, repeated transformations/validation)
Over-engineering (YAGNI) (unused branches, unnecessary abstractions)
Magic numbers / strings (hardcoded values without semantic constants)
Structural clarity (deep nesting, unreadable one-liners, nested ternaries)
Project conventions (imports/order/style consistency)

从以下维度评审代码差异（及附近受影响的代码）：

有意义的命名（避免
```
data1
```
、
```
tmp
```
，同一概念命名统一）
小函数/单一职责原则（过长函数、参数过多、职责混杂）
消除重复（DRY）（复制粘贴逻辑、重复的转换/验证）
避免过度设计（YAGNI）（未使用的分支、不必要的抽象）
魔法值/字符串（未使用语义化常量的硬编码值）
结构清晰度（深层嵌套、难以阅读的单行代码、嵌套三元表达式）
项目约定（导入/顺序/风格一致性）

3) Docs ↔ code consistency scan

3) 文档与代码一致性扫描

Check that docs do not lie:

Enumerate:
```
README.md
```
,
```
docs/**/*.md
```
, config examples, env keys, API contracts
For each claim/config/example: locate the authoritative code/config/contracts
Record mismatches with evidence (doc location + code location)

检查文档是否准确：

枚举范围：
```
README.md
```
、
```
docs/**/*.md
```
、配置示例、环境变量键、API契约
针对每个声明/配置/示例：定位对应的权威代码/配置/契约
记录不匹配项并提供证据（文档位置 + 代码位置）

Output (required)

输出要求

Produce a structured report:

```
quality-review.md
```
```
quality-review.json
```
(optional but recommended)

If you are working inside a Ship Faster run directory, write to:

```
run_dir/evidence/quality-review.md
```
```
run_dir/evidence/quality-review.json
```

If triage selects React/Next performance review and a Ship Faster

run_dir

is available, also persist:

run_dir/evidence/react-best-practices-review.md

If triage selects UI guidelines audit and a Ship Faster

run_dir

is available, also persist:

run_dir/evidence/ui-guidelines-review.md

(terse

file:line

findings, grouped by file)

生成结构化报告：

```
quality-review.md
```
```
quality-review.json
```
（可选但推荐）

若在Ship Faster运行目录内工作，写入至：

```
run_dir/evidence/quality-review.md
```
```
run_dir/evidence/quality-review.json
```

若分流结果选择了React/Next性能评审且Ship Faster

run_dir

可用，同时保存：

run_dir/evidence/react-best-practices-review.md

若分流结果选择了UI规范审计且Ship Faster

run_dir

可用，同时保存：

run_dir/evidence/ui-guidelines-review.md

（简洁的

file:line

格式结果，按文件分组）

Output format (recommended)

Summary

摘要

Verdict: Ready / With fixes / Not ready
Scope: BASE_SHA..HEAD_SHA (or file list)

判定：就绪 / 需修复 / 未就绪
范围：BASE_SHA..HEAD_SHA（或文件列表）

Triage

分流结果

Docs-only: yes|no
React/Next perf review: yes|no
UI guidelines audit: yes|no
Reason: ...

仅文档变更：是|否
React/Next性能评审：是|否
UI规范审计：是|否
原因：...

Strengths

优势

Issues

问题

Critical (Must Fix)

严重（必须修复）

Location: path:line
- What
- Why it matters
- Minimal fix

位置：路径:行号
- 问题描述
- 影响原因
- 最小修复方案

Important (Should Fix)

重要（建议修复）

...

Minor (Nice to Have)

次要（可选优化）

...

UI Guidelines (terse, only if audit=yes)

UI规范审计结果（仅当审计=是时展示）

path:line <finding>
path:line <finding>

undefined

路径:行号 <问题描述>
路径:行号 <问题描述>

undefined

review-quality

Original

Translation

Quality Review (Unified)

统一质量评审

Inputs (recommended)

推荐输入

Suggested scope commands

推荐范围命令

Baseline: main/master merge-base

基准：main/master分支的合并基点

Process

流程

0) Auto-triage (Built-in Router)

0) 自动分流（内置路由）

Triage

分流结果

1) Merge readiness (verdict review)

1) 合并就绪性（判定评审）

2) Clean Code maintainability scan

2) Clean Code可维护性扫描

3) Docs ↔ code consistency scan

3) 文档与代码一致性扫描

Output (required)

输出要求

Output format (recommended)

推荐输出格式

Summary

摘要

Triage

分流结果

Strengths

优势

Issues

问题

Critical (Must Fix)

严重（必须修复）

Important (Should Fix)

重要（建议修复）

Minor (Nice to Have)

次要（可选优化）

UI Guidelines (terse, only if audit=yes)

UI规范审计结果（仅当审计=是时展示）