review-quality

品質レビュー（統合版）

目標：「この変更は良いか？」という問いを、明確なマージ／本番環境へのリリース準備状況の判定を伴う、繰り返し実施可能なレビューに変えることです。

このスキルでは、意図的に3つのレビュー観点を統合しています。

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 を使用します。

最低限の確認項目：

• 要件との整合性（受け入れ基準を満たしているか、対象外の要件を守っているか）
• 副作用が適切に制御されているか（デプロイ／決済／DB 書き込みには明示的な承認が必要です）
• エラー処理が明示されているか（エラーを黙って無視していないか）
• 検証の証拠があるか（テスト／ビルド／型チェック／リンター／手動手順）

2) クリーンコードの保守性スキャン

差分（および変更箇所の周辺コード）を、以下の観点で確認します。

1. 意味のある命名（data1 や tmp を避け、同じ概念に異なる命名を使わない）
2. 小さな関数／単一責任の原則（SRP）（非常に長い関数、パラメーターが多すぎる関数、責務が混在している関数）
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 が利用可能な場合は、以下も保存します（ファイルごとにグループ化した簡潔な file:line 形式の指摘事項）。

• run_dir/evidence/ui-guidelines-review.md

出力形式（推奨）

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