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.
Inputs (recommended)
BASE_SHA and HEAD_SHA for diff-based reviews
- Optional:
PLAN_OR_REQUIREMENTS path (e.g. run_dir/evidence/features/<feature_slug>-plan.md)
- Optional: docs scope (
README.md, docs/**, API contracts)
- Optional:
run_dir (Ship Faster run directory, if available)
Suggested scope commands
# 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"
Process
0) Auto-triage (Built-in Router)
Goal: reduce user choice. The reviewer decides which specialized review lens to apply, deterministically, based on the diff.
Collect signals (minimum):
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):
## 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) Merge readiness (verdict review)
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)
2) Clean Code maintainability scan
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)
3) Docs ↔ code consistency scan
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)
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)
Output format (recommended)
## 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>
1---2name: review-quality3description: "Unified codebase quality review: merge readiness verdict + maintainability (Clean Code) + docs-vs-code consistency. Use for code review, quality check, refactor check, outdated docs check, or merge/production readiness."4metadata:5 source: https://skillmd.com/skills/enuno/review-quality6---78# Quality Review (Unified)910Goal: turn “is this change good?” into a **repeatable review** with a clear **merge/production readiness** verdict.1112This skill intentionally merges three review lenses:13141) **Merge readiness** (requirements alignment + risk + verification)152) **Code maintainability** (Clean Code-style review)163) **Documentation consistency** (README/docs vs implementation)1718This is the **single entry point** for Ship Faster reviews. It includes an internal auto-triage:19- Always run the unified review (this skill).20- If React/Next.js performance risk is detected, also run `review-react-best-practices` and include its findings.21- 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.2223## Inputs (recommended)2425- `BASE_SHA` and `HEAD_SHA` for diff-based reviews26- Optional: `PLAN_OR_REQUIREMENTS` path (e.g. `run_dir/evidence/features/<feature_slug>-plan.md`)27- Optional: docs scope (`README.md`, `docs/**`, API contracts)28- Optional: `run_dir` (Ship Faster run directory, if available)2930### Suggested scope commands3132```bash33# Baseline: main/master merge-base34BASE_SHA=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master)35HEAD_SHA=$(git rev-parse HEAD)3637git diff --stat "$BASE_SHA..$HEAD_SHA"38git diff "$BASE_SHA..$HEAD_SHA"39```4041## Process4243### 0) Auto-triage (Built-in Router)4445Goal: reduce user choice. The reviewer decides which specialized review lens to apply, deterministically, based on the diff.4647Collect signals (minimum):4849```bash50git diff --name-only "$BASE_SHA..$HEAD_SHA"51git diff --stat "$BASE_SHA..$HEAD_SHA"52git diff "$BASE_SHA..$HEAD_SHA"53```5455Routing rules (apply in order):56571) **Docs-only change** (fast path):58 - If every changed file is in `docs/**` or ends with `.md|.txt|.rst`59 - Then run the unified review, but focus on **Docs ↔ Code consistency** + **release risk** (skip deep code maintainability unless docs reference code changes).60612) **React/Next.js performance-sensitive change**:62 - If any changed file matches:63 - `**/*.tsx`, `**/*.jsx`64 - `next.config.*`, `app/**`, `pages/**`, `src/app/**`, `src/pages/**`65 - React/Next entrypoints (`layout.tsx`, `page.tsx`, `middleware.ts`, `route.ts`, `loading.tsx`)66 - Or the diff contains performance-sensitive keywords (spot check via `git diff`):67 - `use client`, `Suspense`, `dynamic(`, `next/dynamic`, `next/navigation`, `React.cache`, `revalidate`, `fetch(`, `headers()`, `cookies()`68 - Then: run `review-react-best-practices` and include its output (or link to its artifact) in the final report.69703) **UI Web Interface Guidelines audit** (a11y/UX rules, terse output):71 - If any changed file matches:72 - UI code: `**/*.tsx`, `**/*.jsx`, `**/*.vue`, `**/*.html`, `**/*.css`, `**/*.scss`73 - Common UI dirs: `app/**`, `pages/**`, `src/app/**`, `src/pages/**`, `components/**`, `src/components/**`74 - Then: fetch the latest Web Interface Guidelines and audit only the changed UI files first.75 - Source: `https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md`76 - Fetch method: WebFetch (if available) or `curl -fsSL <url>`77 - Output findings in **terse `file:line` format**, grouped by file (high signal, low prose). Treat a11y + focus issues as higher severity than cosmetic issues.7879Output requirement (at top of your report):8081```md82## Triage83- Docs-only: yes|no84- React/Next perf review: yes|no85- UI guidelines audit: yes|no86- Reason: <1-3 bullets based on file paths / patterns>87```8889### 1) Merge readiness (verdict review)9091Use the template: `references/code-reviewer.md`.9293Minimum checks:94- Requirements alignment (acceptance criteria hit, non-goals respected)95- Side effects are gated (deploy/payments/DB writes require explicit approval)96- Error handling is explicit (no silent failures)97- Verification evidence exists (tests/build/typecheck/lint/manual steps)9899### 2) Clean Code maintainability scan100101Review the diff (and nearby touched code) across these dimensions:1021031. **Meaningful naming** (avoid `data1`, `tmp`, mixed naming for same concept)1042. **Small functions / SRP** (very long functions, too many params, mixed responsibilities)1053. **Duplication (DRY)** (copy/paste logic, repeated transformations/validation)1064. **Over-engineering (YAGNI)** (unused branches, unnecessary abstractions)1075. **Magic numbers / strings** (hardcoded values without semantic constants)1086. **Structural clarity** (deep nesting, unreadable one-liners, nested ternaries)1097. **Project conventions** (imports/order/style consistency)110111### 3) Docs ↔ code consistency scan112113Check that docs do not lie:114- Enumerate: `README.md`, `docs/**/*.md`, config examples, env keys, API contracts115- For each claim/config/example: locate the authoritative code/config/contracts116- Record mismatches with evidence (doc location + code location)117118## Output (required)119120Produce a structured report:121122- `quality-review.md`123- `quality-review.json` (optional but recommended)124125If you are working inside a Ship Faster run directory, write to:126- `run_dir/evidence/quality-review.md`127- `run_dir/evidence/quality-review.json`128129If triage selects React/Next performance review and a Ship Faster `run_dir` is available, also persist:130- `run_dir/evidence/react-best-practices-review.md`131132If triage selects UI guidelines audit and a Ship Faster `run_dir` is available, also persist:133- `run_dir/evidence/ui-guidelines-review.md` (terse `file:line` findings, grouped by file)134135## Output format (recommended)136137```md138## Summary139- Verdict: Ready / With fixes / Not ready140- Scope: BASE_SHA..HEAD_SHA (or file list)141142## Triage143- Docs-only: yes|no144- React/Next perf review: yes|no145- UI guidelines audit: yes|no146- Reason: ...147148## Strengths149- ...150151## Issues152### Critical (Must Fix)153- Location: path:line154 - What155 - Why it matters156 - Minimal fix157158### Important (Should Fix)159...160161### Minor (Nice to Have)162...163164## UI Guidelines (terse, only if audit=yes)165- path:line <finding>166- path:line <finding>167```