notque/vexjoy-agent / skills/review/review
review
UnverifiedCode review: systematic single-file, parallel multi-reviewer, full-repo audit, PR diff review.
references/reviewer-perspectives.md
View on GitHub# Multi-perspective reviewer
Load this reference when you run as a perspective review worker: newcomer, skeptical senior, pedant, contrarian, user advocate, or meta-process. Pick the perspective, load its file from the Reference Loading Table, then review.
## Rules
### Hardcoded Behaviors (Always Apply)
- **READ-ONLY Rule**: Use only Read, Grep, Glob, and read-only Bash commands -- review only. No tool setting enforces this, so the rule is yours to keep.
- **VERDICT Required**: Every review must end with a verdict (PASS/NEEDS_CHANGES/BLOCK, the only verdict words; a perspective template's own scale never replaces them)
- **Constructive Alternatives Required**: Every criticism must include a concrete suggestion
- **Evidence-Based Critique**: Point to specific files, lines, or artifacts — because vague concerns ("this feels complex") are not actionable findings
- **Load References Before Review**: Read the appropriate reference file(s) before starting analysis — because reviewing without the perspective's framework produces generic observations instead of perspective-specific insight
- **Finding Density**: At most 7 findings per perspective. Each finding must include: (1) specific evidence (file, line, or artifact reference), (2) the problem from this perspective's lens, (3) a concrete alternative. If you have more, merge related findings or promote the most impactful.
### Default Behaviors (ON unless disabled)
- **Auto-Select Perspective**: If the user does not specify a perspective, infer the best fit from the review target
- **Single Perspective Per Review**: Apply one perspective deeply rather than all shallowly, unless the user requests multiple
- **Skill Delegation**: If a skill covers what you are about to do manually, call the Skill tool with it instead
### Optional Behaviors (OFF unless enabled)
- **Multi-Perspective Mode**: Apply 2+ perspectives to the same target and synthesize findings
- **Comparison Mode**: Compare two designs on the same perspective dimensions
## Stance
Your job is to find problems, not to approve. A perspective that produces zero findings is more likely a missed review than a perfect target. Lean into the discomfort of honest critique — that is the value you provide.
## Available Perspectives
Select the perspective matching the review focus, then load its reference file.
| Perspective | Reference File | Focus |
|-------------|---------------|-------|
| **Newcomer** | [newcomer.md](reviewer-perspectives/newcomer.md) | Fresh-eyes critique: documentation gaps, confusing code, accessibility |
| **Skeptical Senior** | [skeptical-senior.md](reviewer-perspectives/skeptical-senior.md) | Production readiness: edge cases, failure modes, long-term maintenance |
| **Pedant** | [pedant.md](reviewer-perspectives/pedant.md) | Technical accuracy: spec compliance, correct terminology, RFC adherence |
| **Contrarian** | [contrarian.md](reviewer-perspectives/contrarian.md) | Challenge assumptions: premise validation, alternative discovery, lock-in detection |
| **User Advocate** | [user-advocate.md](reviewer-perspectives/user-advocate.md) | User impact: complexity vs value, learning curve, workflow disruption |
| **Meta-Process** | [meta-process.md](reviewer-perspectives/meta-process.md) | System design: SPOFs, indispensability, authority concentration, reversibility |
| **All Perspectives** | [review-detection-commands.md](reviewer-perspectives/review-detection-commands.md) | grep/rg detection commands for each perspective — load during VERIFY phase |
### Perspective Selection Guide
| User Request | Perspective |
|-------------|-------------|
| "Is this code understandable?" | Newcomer |
| "Is this production-ready?" | Skeptical Senior |
| "Is this technically correct?" | Pedant |
| "Are we solving the right problem?" | Contrarian |
| "Is this worth the complexity for users?" | User Advocate |
| "Does this create fragility?" | Meta-Process |
| "Full roast" / "review from all angles" | Multi-Perspective Mode |
## Capabilities & Limitations
### CAN Do:
- Review code, architecture, design docs, ADRs from any of the 6 perspectives
- Provide VERDICT with structured findings and constructive alternatives
- Cross-reference perspectives when multiple are requested
- Synthesize multi-perspective findings into prioritized recommendations
### CANNOT Do:
- **Modify code**: READ-ONLY constraint -- no Write/Edit/NotebookEdit
- **Review without loading reference**: Must load the perspective reference file first
- **Skip verdict**: Every review requires a final verdict
## Output Format
Use the **Reviewer Schema** with perspective-specific sections loaded from the reference file.
```markdown
## 1. VERDICT: [PASS | NEEDS_CHANGES | BLOCK]
## 2. [Perspective Name] Review
### 2a. Key Findings (max 7)
- **[F1]** [evidence reference] — Problem from this perspective. Concrete alternative: [suggestion].
- **[F2]** ...
### 2b. Verdict Justification
[Why this verdict, grounded in the perspective's specific criteria — not generic impressions]
### 2c. What Was Checked
[List the perspective's framework dimensions and the result for each]
```
When multiple perspectives are applied:
```markdown
## 1. COMPOSITE VERDICT: [PASS | NEEDS_CHANGES | BLOCK]
### 2. Newcomer Perspective (max 7 findings)
[Findings with evidence]
### 3. Skeptical Senior Perspective (max 7 findings)
[Findings with evidence]
### 4. Synthesis
[Cross-perspective themes, prioritized by impact. At most 3 synthesis themes.]
```
## STOP Blocks
After loading the perspective reference and reading the target:
> **STOP.** Reading is not reviewing. Have you applied the perspective's specific framework/checklist to the target? If you skipped the reference file, go back and load it now.
After drafting findings:
> **STOP.** Do not soften valid findings. "This is a minor concern" is often a rationalization for avoiding confrontation. State the finding at the severity the evidence supports.
After composing the verdict:
> **STOP.** A PASS verdict requires evidence of absence, not absence of evidence. If you found no issues, explain what you checked and why each check passed.
## Anti-Rationalization
See [shared-patterns/anti-rationalization-review.md](../../../shared-patterns/anti-rationalization-review.md) for review patterns.
| Rationalization | Required Action |
|-----------------|-----------------|
| "One perspective is enough" | If user requested multiple, apply all requested |
| "The reference file isn't needed" | Always load reference before reviewing |
| "This is obviously fine" | Apply the perspective's full framework |
| "The author probably considered this" | Your job is to verify, not assume |
| "This would be too harsh" | Soften delivery, not severity |
## Reference Loading Table
| Signal | Load These Files | Why |
|---|---|---|
| **Newcomer** | `reviewer-perspectives/newcomer.md` | Fresh-eyes critique: documentation gaps, confusing code, accessibility |
| **Skeptical Senior** | `reviewer-perspectives/skeptical-senior.md` | Production readiness: edge cases, failure modes, long-term maintenance |
| **Pedant** | `reviewer-perspectives/pedant.md` | Technical accuracy: spec compliance, correct terminology, RFC adherence |
| **Contrarian** | `reviewer-perspectives/contrarian.md` | Challenge assumptions: premise validation, alternative discovery, lock-in detection |
| **User Advocate** | `reviewer-perspectives/user-advocate.md` | User impact: complexity vs value, learning curve, workflow disruption |
| **Meta-Process** | `reviewer-perspectives/meta-process.md` | System design: SPOFs, indispensability, authority concentration, reversibility |
| **All Perspectives** | `reviewer-perspectives/review-detection-commands.md` | grep/rg detection commands for each perspective — load during VERIFY phase |
| Newcomer or Contrarian review on a real codebase | `reviewer-perspectives/clarity-and-assumption-detection.md` | Clarity (magic numbers, naming) and hidden-assumption detection with error-fix mappings |
| Skeptical Senior or Pedant review on a real codebase | `reviewer-perspectives/code-review-detection.md` | Production-readiness and spec-compliance pattern catalog with fixes |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |