Skip to content

notque/vexjoy-agent / skills/review/review

Code review: systematic single-file, parallel multi-reviewer, full-repo audit, PR diff review.

FileKindSize
SKILL.mdskill md11.7 KB
references/architecture-smell-baseline.mdmarkdown6.8 KB
references/audit-playbook.mdmarkdown10.2 KB
references/disprove-pass.mdmarkdown2.3 KB
references/go-review-patterns.mdmarkdown4.0 KB
references/receiving-feedback.mdmarkdown3.0 KB
references/report-template.mdmarkdown1.9 KB
references/reviewer-code.mdmarkdown6.2 KB
references/reviewer-code/code-quality.mdmarkdown4.6 KB
references/reviewer-code/comments.mdmarkdown3.6 KB
references/reviewer-code/config-safety.mdmarkdown3.7 KB
references/reviewer-code/dead-code.mdmarkdown3.2 KB
references/reviewer-code/language-checks.mdmarkdown6.7 KB
references/reviewer-code/language-specialist.mdmarkdown4.7 KB
references/reviewer-code/naming.mdmarkdown3.3 KB
references/reviewer-code/performance.mdmarkdown3.5 KB
references/reviewer-code/simplifier.mdmarkdown5.3 KB
references/reviewer-code/test-analyzer.mdmarkdown4.5 KB
references/reviewer-code/type-design.mdmarkdown4.0 KB
references/reviewer-domain.mdmarkdown9.1 KB
references/reviewer-domain/adr-compliance.mdmarkdown3.0 KB
references/reviewer-domain/business-logic.mdmarkdown4.6 KB
references/reviewer-domain/common-bugs.mdmarkdown6.7 KB
references/reviewer-domain/edge-case-tables.mdmarkdown4.5 KB
references/reviewer-domain/operational-preferred-patterns.mdmarkdown7.2 KB
references/reviewer-domain/pragmatic-builder.mdmarkdown4.2 KB
references/reviewer-domain/production-gaps.mdmarkdown5.3 KB
references/reviewer-domain/sapcc-structural.mdmarkdown5.4 KB
references/reviewer-domain/state-machine-verification.mdmarkdown5.2 KB
references/reviewer-domain/structural-categories.mdmarkdown5.8 KB
references/reviewer-perspectives.mdmarkdown8.0 KB
references/reviewer-perspectives/clarity-and-assumption-detection.mdmarkdown4.8 KB
references/reviewer-perspectives/code-review-detection.mdmarkdown4.4 KB
references/reviewer-perspectives/contrarian.mdmarkdown2.3 KB
references/reviewer-perspectives/meta-process.mdmarkdown2.7 KB
references/reviewer-perspectives/newcomer.mdmarkdown2.0 KB
references/reviewer-perspectives/pedant.mdmarkdown3.3 KB
references/reviewer-perspectives/review-detection-commands.mdmarkdown8.7 KB
references/reviewer-perspectives/skeptical-senior.mdmarkdown2.9 KB
references/reviewer-perspectives/user-advocate.mdmarkdown2.9 KB
references/reviewer-system.mdmarkdown14.0 KB
references/reviewer-system/api-contract.mdmarkdown3.4 KB
references/reviewer-system/compliance-checklists.mdmarkdown5.1 KB
references/reviewer-system/concurrency.mdmarkdown3.6 KB
references/reviewer-system/dependency-audit.mdmarkdown3.3 KB
references/reviewer-system/docs-validator.mdmarkdown4.0 KB
references/reviewer-system/error-messages.mdmarkdown3.1 KB
references/reviewer-system/financial-resilience-de-eu.mdmarkdown5.3 KB
references/reviewer-system/german-it-security.mdmarkdown10.7 KB
references/reviewer-system/industry-specific-compliance.mdmarkdown3.5 KB
references/reviewer-system/migration-safety.mdmarkdown3.3 KB
references/reviewer-system/observability.mdmarkdown3.1 KB
references/reviewer-system/security-authz.mdmarkdown9.0 KB
references/reviewer-system/security-ci-cd.mdmarkdown7.6 KB
references/reviewer-system/security-data-exfil.mdmarkdown9.5 KB
references/reviewer-system/security-finding-template.mdmarkdown3.0 KB
references/reviewer-system/security-injection.mdmarkdown6.3 KB
references/reviewer-system/security-pii.mdmarkdown7.3 KB
references/reviewer-system/security.mdmarkdown3.6 KB
references/reviewer-system/silent-failures.mdmarkdown3.6 KB
references/reviewer-system/sovereign-cloud-data-residency.mdmarkdown6.6 KB
references/reviewer-system/stride-threat-model.mdmarkdown3.2 KB
---
name: review
description: "Code review: systematic single-file, parallel multi-reviewer, full-repo audit, PR diff review."
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
  - Glob
  - Edit
  - Task
  - Agent
routing:
  force_route: true
  not_for: "security scanning (use security), linting (use code-quality), git push/commit/PR (use pr-workflow)"
  triggers:
    - "review code"
    - "code review"
    - "code review methodology"
    - "structured review"
    - "code audit"
    - "review methodology"
    - "comprehensive review"
    - "parallel review"
    - "3-reviewer review"
    - "multi-reviewer"
    - "concurrent review"
    - "full repo review"
    - "review entire repo"
    - "codebase health check"
    - "review all files"
    - "full codebase review"
    - "audit the codebase"
    - "codebase audit"
    - "review whole repo"
    - "sweep all source files"
    - "repo health"
    - "review this PR"
    - "review my PR"
    - "review my changes"
    - "PR review"
    - "pr-review"
    - "diff review"
    - "review code quality"
    - "code conventions"
    - "naming review"
    - "dead code review"
    - "performance review"
    - "type design review"
    - "test coverage review"
    - "config safety review"
    - "adr compliance"
    - "adr review"
    - "adr check"
    - "scope creep"
    - "business logic"
    - "domain review"
    - "edge cases"
    - "state machine"
    - "sapcc structural"
    - "sapcc structural review"
    - "go-bits design"
    - "go-bits usage"
    - "type export"
    - "anti-over-engineering"
    - "pragmatic builder"
    - "production gaps"
    - "operational readiness"
    - "newcomer perspective"
    - "fresh eyes review"
    - "production readiness"
    - "senior review"
    - "skeptical review"
    - "technical accuracy"
    - "spec compliance"
    - "pedantic review"
    - "challenge the premise"
    - "multi-persona critique"
    - "user advocate"
    - "usability review"
    - "is this worth the complexity"
    - "meta-process review"
    - "architecture health"
    - "single point of failure"
    - "complexity audit"
    - "authority concentration"
    - "reversibility check"
    - "system review"
    - "concurrency review"
    - "error handling review"
    - "observability review"
    - "API contract review"
    - "migration safety review"
    - "dependency audit"
    - "API doc accuracy review"
    - "architecture decision"
    - "decision record"
    - "documentation review"
    - "user impact"
    - "user perspective"
    - "user experience"
    - "system design review"
    - "indispensable component"
  category: code-review
  pairs_with:
    - security
    - testing
    - workflow
---

# Review

Three modes. Pick one by request shape, default to systematic.

| Request matches | Mode |
|---|---|
| Review a file, diff, or PR | Systematic (default) |
| "parallel review", "multi-reviewer", "3-reviewer" | Parallel |
| "full repo review", "codebase audit", "repo health", review ALL files | Full-repo |

## Deep References

| Signal | Load | Why |
|---|---|---|
| Reviewing Go code | `references/go-review-patterns.md` | Exports, concurrency, resources, metrics, tests |
| Dispatching Architecture reviewer in parallel mode | `references/architecture-smell-baseline.md` | 12 Fowler smells with language counter-examples and severity cap |
| Writing full-repo report | `references/report-template.md` | Report structure and field definitions |
| Dispatching full-repo wave agents | `references/audit-playbook.md` | 8-category checklists with evidence requirements |
| Disproving findings before report (Systematic Phase 3.5, Parallel Step 3) | `references/disprove-pass.md` | Refuter dispatch, drop rule, fail-open cases, model choice |
| Receiving review feedback | `references/receiving-feedback.md` | Feedback-handling patterns |
| Code-quality review: conventions, naming, dead code, comments, performance, types, tests, config | `references/reviewer-code.md` | Code-quality reviewer method; dimension files in `references/reviewer-code/` |
| System review: security, concurrency, silent failures, errors, observability, API contracts, migrations, dependencies, docs | `references/reviewer-system.md` | System reviewer method; domain files in `references/reviewer-system/` |
| Domain review: ADR compliance, business logic, SAP CC structural, pragmatic builder | `references/reviewer-domain.md` | Domain reviewer method; files in `references/reviewer-domain/` |
| Perspective review: newcomer, skeptical senior, pedant, contrarian, user advocate, meta-process | `references/reviewer-perspectives.md` | Perspective reviewer method; files in `references/reviewer-perspectives/` |

## Severity Classification

Shared across all modes. When in doubt, classify UP.

| Level | Scope | Examples |
|---|---|---|
| BLOCKING | Security, correctness, reliability | Auth bypass, race condition, resource leak, logic error, test failure |
| SHOULD FIX | Material quality, patterns, tests | Missing tests, unhelpful errors, pattern violations, N+1 in hot paths |
| SUGGESTION | Optional, stylistic | Naming preferences, comments, micro-optimizations |

Decision: security/correctness/reliability risk? -> BLOCKING. Violates patterns or creates maintenance burden? -> SHOULD FIX. Purely stylistic? -> SUGGESTION.

## Verdict Rules

| Condition | Verdict |
|---|---|
| Any BLOCKING (parallel: CRITICAL) finding | **BLOCK** |
| SHOULD FIX (parallel: HIGH) findings, no BLOCKING | **NEEDS_CHANGES** |
| Only SUGGESTION or clean | **PASS** |

These are the only verdict words, the same PASS / NEEDS_CHANGES / BLOCK the reviewer references prescribe. An open question that stops a PASS is NEEDS_CHANGES with the question stated. The validator rejects a verdict that contradicts the findings (PASS over SHOULD FIX, anything but BLOCK over BLOCKING).

Omit empty severity sections. Include review scope, evidence, and limitations. Validate output (`--type parallel` for Mode 2):

```bash
python3 ~/.claude/scripts/validate-review-output.py --type systematic /tmp/review-output.md
```

Exit 0 = valid; 1 = schema errors; 2 = unparseable; 3 = missing jsonschema.

---

## Mode 1: Systematic Review (default)

Single-reviewer, 4-phase review of a named file, diff, or PR.

### Phase 1: UNDERSTAND

Read the repo's diff-triggered checklist from the default branch (`git show origin/main:REVIEW.md`) and apply matching rows to the diff. Read repository instructions and the complete diff. Read surrounding code to understand each changed path and its consumers. When signatures change, find all callers and interface implementations. Trace parameters to their source: query params may hold any user string; tokens may be server-issued IDs; enums have bounded values. Check validation at each caller.

**Gate:** Every changed path accounted for, callers traced where needed.

### Phase 2: VERIFY

Run relevant tests and required repository checks. Reuse prior results only when they cover current code and environment. Check material claims in comments and PR description against code and tests. Missing tools, skipped checks, and inferred outcomes are not passes.

**Gate:** Claims have supporting evidence; required checks passed or the gap is recorded.

### Phase 3: ASSESS

Assess risks: security (auth, validation, injection, secrets), performance (N+1, unbounded work, allocations on hot paths), architecture (conventions, compatibility, scope, unnecessary abstractions). For extracted helpers, recheck contract and callers.

**Gate:** Relevant risks and remaining uncertainty are explicit.

### Phase 3.5: VERIFY FINDINGS

Before reporting, check each finding's input sequence, existing guards, and proposed fix. Drop unreachable or already-handled claims. Deduplicate when combining reviews; resolve severity from evidence. Then run the disprove pass in `references/disprove-pass.md`: it drops findings refuted by quoted code and keeps the rest.

### Phase 4: DOCUMENT

```text
Review Summary:
  Files Reviewed: N | Lines Changed: +X/-Y
  Test Status: PASS | FAIL | SKIPPED
  Risk Level: LOW | MEDIUM | HIGH | CRITICAL

BLOCKING:
  1. Issue and consequence — path/file.ext:42
SHOULD FIX:
  1. Issue and consequence — path/file.ext:52
SUGGESTIONS:
  1. Optional improvement — path/file.ext:62

Verdict: PASS | NEEDS_CHANGES | BLOCK
Rationale: Evidence, scope, and limitations.
```

---

## Mode 2: Parallel Review

Three concurrent reviewers, then aggregate.

### Step 1: Scope

Identify the diff or files. Record the reviewed revision.

```bash
git diff --name-only HEAD
gh pr view --json files -q '.files[].path'
```

Select the Architecture reviewer's reference by language: Go -> `programming` skill, `golang-general.md`; Python -> `programming`, `python-general.md`; TypeScript -> `frontend`, `typescript-frontend.md`; mixed -> built-in `Explore` with no reference.

### Step 2: Dispatch

Dispatch three reviewers together, each a fresh `general-purpose` worker (Agent tool `subagent_type: "general-purpose"`) so each review stays independent. Read-only; no code edits. Start each prompt with the reviewer's Skill call and reference read line: "Read ~/.claude/skills/<skill>/references/<file> and follow it; load every file its Reference Loading Table matches."

| Reviewer | Focus | Loads |
|---|---|---|
| Security | Auth, authorization, input validation, secrets, OWASP | `review`, `reviewer-system.md` (security domain) |
| Business Logic | Requirements, edge cases, state transitions, failure modes | `review`, `reviewer-domain.md` (business-logic domain) |
| Architecture | Design, structure, performance, maintainability, scope | language reference from Step 1 |

Pass `references/architecture-smell-baseline.md` verbatim to the Architecture reviewer. Require `[Reviewer] file:line` format with severity and consequence.

### Step 3: Aggregate and Verdict

Deduplicate findings, resolve severity disagreements from evidence. Run the disprove pass in `references/disprove-pass.md` on the merged list. Apply shared verdict rules. Output a single combined report with severity matrix, combined findings, summary by reviewer, and a recommendation line `**BLOCK**`, `**NEEDS_CHANGES**` or `**PASS**` followed by ` - ` and the rationale.

**Gate:** Every reviewer returned, or missing coverage is explicitly stated without claiming approval.

---

## Mode 3: Full-Repo Review

All source files through a 4-wave comprehensive review. Produces a prioritized backlog, not auto-fixes. Use for quarterly health checks, post-refactor audits, or new codebase onboarding.

Options: `--directory [dir]` (scope to one dir), `--skip-precheck`, `--min-severity [level]`.

### Step 1: Discover and Pre-check

Scan all source files (scripts/, hooks/, skills/, agents/, docs/). Never fall back to git diff.

```bash
python3 ~/.claude/scripts/score-component.py --all-agents --all-skills --json
```

Save scores as triage context. A score alone never determines severity.

### Step 2: Run Comprehensive Review

Call `comprehensive-review` with `--review-only` and the full file list. Run all 4 waves (0-3). Load `references/audit-playbook.md` as prompt context for wave agents.

### Step 3: Report

Merge deterministic scores with LLM findings. Identify systemic patterns (3+ files). Write `full-repo-review-report.md` using `references/report-template.md`.

**Gate:** Report exists with severity sections and deterministic scores.

---

## Error Handling

| Error | Solution |
|---|---|
| Reviewer times out or returns nothing | Report partial findings, note gap, retry on reduced scope |
| Disprove pass fails or returns unparseable output | Keep all findings, note the gap in the verdict |
| Validator script missing | Run review without validation, note gap in verdict |
| score-component.py fails | Proceed with LLM review only, note gap in report |
| Too many files for single session | Split by directory: scripts/, hooks/, agents/, skills/ |
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall