review-quality

质量审查（统一版）

目标：将“这项变更是否合格？”转化为一项可重复的审查，并给出明确的合并/生产就绪度结论。

此技能有意整合了三个审查视角：

1. 合并就绪度（需求一致性 + 风险 + 验证）
2. 代码可维护性（Clean Code 风格审查）
3. 文档一致性（README/文档与实现是否一致）

这是 Ship Faster 审查的统一入口。它包含内部自动分流机制：

• 始终运行统一审查（此技能）。
• 如果检测到 React/Next.js 性能风险，还要运行 review-react-best-practices，并纳入其发现。
• 如果检测到 UI 界面变更，还要执行 Web Interface Guidelines 审查（无障碍/焦点/表单/动效/内容溢出），并以简洁的 file:line 格式列出发现。

输入（推荐）

• 基于差异的审查使用 BASE_SHA 和 HEAD_SHA
• 可选：PLAN_OR_REQUIREMENTS 路径（例如 run_dir/evidence/features/<feature_slug>-plan.md）
• 可选：文档范围（README.md、docs/**、API 契约）
• 可选：run_dir（Ship Faster 运行目录，如有）

建议的范围命令

# Baseline: main/master merge-base
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"

流程

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

目标：减少用户选择。审查者根据差异，以确定性方式决定采用哪些专门审查视角。

收集信号（最低要求）：

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

路由规则（按顺序应用）：

1. 仅文档变更（快速路径）：

   • 如果所有变更文件都位于 docs/**，或以 .md|.txt|.rst 结尾
   • 则运行统一审查，但重点关注文档 ↔ 代码一致性和发布风险（除非文档引用了代码变更，否则跳过深入的代码可维护性审查）。

2. 对性能敏感的 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，并在最终报告中纳入其输出（或其产物链接）。

3. UI Web Interface Guidelines 审查（无障碍/UX 规则，输出简洁）：

   • 如果任何变更文件匹配：
     • UI 代码：**/*.tsx、**/*.jsx、**/*.vue、**/*.html、**/*.css、**/*.scss
     • 常见 UI 目录：app/**、pages/**、src/app/**、src/pages/**、components/**、src/components/**
   • 则获取最新版 Web Interface Guidelines，并优先只审查变更的 UI 文件。
     • 来源：https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
     • 获取方式：WebFetch（如可用）或 curl -fsSL <url>
   • 按文件分组，以简洁的 file:line 格式输出发现（高信噪比，少用文字）。无障碍和焦点问题的严重程度高于外观问题。

报告开头的输出要求：

## 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>

1) 合并就绪度（结论审查）

使用模板：references/code-reviewer.md。

最低检查项：

• 需求一致性（是否满足验收标准、是否遵守非目标）
• 副作用是否受控（部署/支付/数据库写入需要明确批准）
• 错误处理是否明确（无静默失败）
• 是否存在验证证据（测试/构建/类型检查/lint/手动步骤）

2) Clean Code 可维护性扫描

从以下方面审查差异（以及附近改动的代码）：

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

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

检查文档是否准确：

• 列出：README.md、docs/**/*.md、配置示例、环境变量键、API 契约
• 对于每项声明/配置/示例，找到权威代码/配置/契约
• 记录不一致之处及证据（文档位置 + 代码位置）

输出（必需）

生成结构化报告：

• 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 问题，按文件分组）

输出格式（推荐）

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

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

## 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)
- path:line <finding>
- path:line <finding>