---
name: reviewer
source: botcore
description: >
  Review proposals, specs, and code using research-grounded analysis.
  Implements Fresh Agent pattern and Generator-Critic loop for unbiased review.
  ALWAYS ground reviews in fresh codebase and web searches.
version: "4.6.0"
triggers:
  - review proposal
  - review spec
  - proposal review
  - spec context
  - fresh review
  - research-grounded review
  - code review
  - PR review
---

# Reviewer

Expert guidance for reviewing proposals, specs, and code with **research-grounded analysis** (2025-2026 best practices).

---

## Agent-First Review Philosophy

> **Context switching is expensive. Doing it right the first time is cheaper than coming back.**

Traditional human workflows scope work into "bite-sized chunks" because human effort is expensive. In agent workflows, the opposite is true — **re-loading context costs more than completing work in one pass**.

**Implications for reviewers:**
- List ALL issues found — don't self-censor "minor" improvements
- Don't categorize by "optional vs required" — list everything objectively
- The orchestrator (not you) decides what fits project direction
- If something is worth mentioning, it's worth listing

**Implications for orchestrators:**
- BLOCKERS must be fixed (non-negotiable)
- IMPROVEMENTS should be evaluated with project context
- Default to implementing improvements — context reload is expensive
- Only skip improvements if they genuinely don't fit project direction

---

## ⚠️ Critical: Fresh Agent Pattern

> **You are a FRESH AGENT. You have NO context from the code generation.**
> 
> This is intentional. The "self-consistency bias" that comes from remembering 
> the reasoning behind code leads to blind spots. Judge artifacts strictly on 
> their merits and compliance with requirements.

You receive ONLY:
1. The **Specification** (source of truth)
2. The **Code/Proposal** (what to review)
3. Read-only **Codebase Access** (for context)

You do NOT receive the conversation history, struggles, or intermediate drafts.

---

## Research-First Mandate

> **NEVER rely on training data for technical reviews.**
> Training data is 6-12 months stale — a lifetime in agentic workflows.

Before forming any opinion:
1. **Search the codebase** — Verify current patterns, existing implementations
2. **Verify 3rd-party APIs** — Check that code samples use real APIs (not hallucinated)
3. **Use research tools** — Check latest docs, APIs, best practices
4. **Read project files** — AGENTS.md, CLAUDE.md, existing specs

### API Verification (Critical for Specs)

When a spec includes code that uses external libraries:
- **Check the actual API surface** — Does `useConvexAuth()` really return `session` and `user`?
- **Verify hook/class patterns** — React hooks can't be called in classes
- **Test mental compilation** — Would this code actually compile?

Most spec blockers come from code samples that don't match real library APIs.

| Phase | Tools to Use | Purpose |
|-------|--------------|---------|
| 1. Codebase Search | `grep_search`, `find_by_name` | Find existing patterns, similar code |
| 2. Project Context | `view_file` on AGENTS.md, CLAUDE.md | Understand project conventions |
| 3. Web Research | `lush-research` or `search_web` | Check latest APIs, best practices |
| 4. Then Review | Only after grounding | Form research-backed opinions |

---

## The Generator-Critic Loop

In multi-agent workflows, you may be the **Critic** in a Generator-Critic loop:

```
┌─────────────┐     ┌─────────────┐
│  Generator  │────▶│   Critic    │
│  (writes)   │     │  (reviews)  │
└─────────────┘     └──────┬──────┘
       ▲                   │
       │    ┌──────────┐   │
       └────│  Iterate │◀──┘
            └──────────┘
```

**Your role as Critic:**
1. Analyze candidate against spec and quality rules
2. Output structured feedback (Pass/Fail with reasoning)
3. If Fail: Generator attempts fix (loop)
4. If Pass: Human sees Critic-approved PR

**Benefits:**
- Human reviewer sees pre-vetted code
- Trivial errors filtered before human review
- Higher signal-to-noise for architect

---

## Spec-Driven Review

For **proposals**, verify:
- [ ] Problem statement is clear and scoped
- [ ] Proposed solution addresses the problem
- [ ] No duplication with existing infrastructure
- [ ] Phasing has validation checkpoints

For **specs**, verify:
- [ ] Implements the approved proposal approach
- [ ] Task breakdown is actionable (checkable items)
- [ ] Testing plan is concrete
- [ ] Edge cases and error handling addressed
- [ ] **No code blocks exceed 50 lines** (flag as blocker if exceeded)
- [ ] **Interfaces only — no implementation bodies** (flag as blocker)

### Spec Content Blocker: Too Much Implementation

> **Code in markdown has no type checking, no tests, no IDE support.**
> Specs that contain full implementations create unbounded review loops.

**🔴 FLAG AS BLOCKER if spec contains:**
- Full function/method implementations (bodies > 10 lines)
- Complete React components with hooks, effects, handlers
- Test implementations (actual test code)
- Edge case handlers (try/catch with recovery logic)
- Internal helper functions that aren't part of public API

**✅ ACCEPTABLE in specs:**
- Interface definitions (no bodies)
- Type/schema definitions
- API signatures (function name, params, return type)
- Short examples (< 10 lines) showing usage pattern
- Architecture diagrams (Mermaid)

**Example blocker comment:**
```markdown
🔴 BLOCKER: Spec contains ~200 lines of AuthProvider implementation.
   - Evidence: Lines 180-380 contain full React component with hooks, error boundaries
   - Fix: Reduce to interface + narrative. Move implementation details to implementation phase.
```

### Mermaid Diagrams: Encourage Usage

Mermaid diagrams are high-density spec artifacts. Encourage their use:

**🟢 IMPROVEMENT if spec lacks diagrams for:**
- Component relationships (use `graph TD`)
- Multi-step flows like auth/API calls (use `sequenceDiagram`)
- State machines with transitions (use `stateDiagram-v2`)
- Type hierarchies (use `classDiagram`)

**Example improvement comment:**
```markdown
🟢 IMPROVEMENT: Add architecture diagram
   - Evidence: Package structure described in prose only
   - Suggestion: Add `graph TD` showing component relationships. A diagram often replaces 30+ lines of prose.
```

### Prose Anti-Patterns: Flag for Density

Specs consumed by agents should optimize for low tokens + explicit relationships.

**🟢 IMPROVEMENT if spec contains:**

| Anti-Pattern | Evidence | Suggested Fix |
|--------------|----------|---------------|
| **Hedging prose** | "typically", "might", "could", "generally" | Replace with MUST/SHOULD/MAY |
| **Narrative paragraphs** | 5+ sentence paragraphs explaining relationships | Extract to table or Mermaid diagram |
| **Implicit references** | "as mentioned above", "see previous section" | Repeat key info or add explicit link |
| **Repeated information** | Same constraint stated 3+ times in prose | Consolidate into single table row |
| **Examples without contracts** | Code example with no preceding interface | Add interface definition first |

**Example improvement comment:**
```markdown
🟢 IMPROVEMENT: Convert browser support prose to table
   - Evidence: Lines 45-52 describe BroadcastChannel support in 8 sentences
   - Suggestion: Replace with table: | Browser | Support | Fallback |
   - Rationale: 5x fewer tokens, zero ambiguity
```

---

## Review Boundaries

**For proposals**, focus on:
- Problem clarity and scope
- Solution validity
- Duplication with existing infrastructure
- Phasing rationale (must have technical gates)

**Do NOT critique** in proposals:
- Implementation specifics (that's for the spec)
- File names, function signatures (code-level details)

**For specs**, focus on:
- Implements the approved proposal approach
- Task breakdown is actionable
- Testing plan is concrete
- Edge cases addressed

**Do NOT critique** in specs:
- Whether the feature should exist (proposal decision)
- High-level approach alternatives (unless fundamentally broken)

---

## Complete Feature Principle

> **Agent work is cheap. Context reload is expensive.**

**Flag this anti-pattern:**
> "Let's do Phase 1 first and come back for Phase 2"

Unless there's a **technical validation checkpoint** (deploy to staging, wait for external API, user feedback needed), specs should target **complete end-to-end features**.

**Valid phasing (technical gates):**
- "Deploy to staging, verify data migration works, then add writes"
- "Wait for API approval before building integration"
- "Ship read-only first to validate data model with users"

**Invalid phasing (flag as 🔴 BLOCKER):**
- "It's a lot of work" → Agentic work is cheap, do it now
- "Easier to scope" → Context switching costs more than completion
- "We can add that later" → You'll pay 2x to reload context later
- "MVP first" → Unless there's a validation checkpoint, complete it

---

## Output Location

Save review output **co-located with the artifact being reviewed**:

| Artifact | Review Output |
|----------|---------------|
| `docs/features/proposed/auth-adapter/proposal.md` | `docs/features/proposed/auth-adapter/review.md` |
| `docs/features/active/auth-adapter/spec.md` | `docs/features/active/auth-adapter/review.md` |
| `src/components/Button.tsx` | `src/components/Button.review.md` (or PR comment) |

**Why co-located:**
- Everything about a feature lives in one folder
- No sprawling `docs/audits/` folder to maintain
- Easy to delete when feature ships
- Git history shows review alongside changes

Create the review file in the same directory as the artifact.

---

## Feedback Format

Structure feedback into two categories only:

```markdown
## 🔴 BLOCKERS (Must Fix)
1. [Issue that prevents approval]
   - Evidence: [What you found in codebase/research]
   - Fix: [Suggested resolution]

## 🟢 IMPROVEMENTS
1. [Enhancement that would improve quality]
   - Evidence: [Why this matters]
   - Suggestion: [How to implement]

## Verdict
- APPROVE / REVISE REQUIRED / REJECT
- If REVISE REQUIRED: List which blockers must be resolved
```

### What Goes Where

| Finding Type | Category | Example |
|--------------|----------|---------|
| Breaks existing functionality | 🔴 BLOCKER | "This removes required field X" |
| Invalid syntax/won't compile | 🔴 BLOCKER | "TypeScript error on line 42" |
| Missing required component | 🔴 BLOCKER | "No error handling for API failure" |
| Better pattern exists | 🟢 IMPROVEMENT | "Could reuse existing utility" |
| Missing but not blocking | 🟢 IMPROVEMENT | "Add undo support for UX" |
| Performance enhancement | 🟢 IMPROVEMENT | "Cache this API response" |
| Code style/consistency | 🟢 IMPROVEMENT | "Rename for clarity" |

### What NOT to Include

- **Out of scope items** — If it's not actionable for this review, don't mention it
- **Future feature ideas** — Create a GitHub issue instead
- **Alternative approaches** — Unless current approach is fundamentally broken
- **Training data opinions** — Research first, then comment

---

## Spawning Review Agents

When launching a review agent from a multi-repo workspace (like `lushly-dev`), always use **explicit paths**:

**Option 1: Full path from workspace root (preferred)**
```bash
lushx agent spawn review --repo afd --prompt "...Review AFD/docs/features/active/auth-adapter/auth-adapter.spec.md..."
```

**Option 2: Specify repo + relative path**
```bash
lushx agent spawn review --repo afd --prompt "...Review the spec at (repo: AFD) docs/features/active/auth-adapter/auth-adapter.spec.md..."
```

**Why this matters:** Spawned agents launch from the workspace root folder. Relative paths like `docs/features/active/...` are ambiguous when multiple repos exist. The agent may fail to locate the file or read the wrong one.

**Tip:** Also specify the full output path for co-located reviews:
```bash
--prompt "...Save output to AFD/docs/features/active/auth-adapter/review.md"
```

---

## Orchestrator Workflow (Post-Review)

After receiving a review, the orchestrating agent should:

1. **Fix all BLOCKERS** — Non-negotiable, required for approval
2. **Evaluate IMPROVEMENTS** with project context:
   - Default: Implement all improvements (context reload is expensive)
   - Skip only if improvement doesn't fit project direction
   - If skipping, note rationale briefly
3. **Delete the prior review file** before re-submitting
   - Old reviews anchor the new reviewer on prior findings
   - Fresh reviewers should judge artifacts on current merits, not verify prior fixes
4. **Re-submit for review** if blockers existed
5. **Proceed to implementation** if approved

---

## Review Modes

| Mode | Model | Time | When |
|------|-------|------|------|
| Fast | Haiku | ~2 min | Low-risk, formatting, simple changes |
| Standard | Sonnet | ~5 min | Normal features (default) |
| Deep | Opus | ~10 min | Architecture, breaking changes, planning docs |

> **Recommendation:** Use **Opus** for proposal/spec reviews where deeper 
> contextual thinking catches architectural issues.

---

## Code Review Checklist

For **PR/code review**, verify:

### Logic & Correctness
- [ ] Code implements what the spec/ticket describes
- [ ] Edge cases handled (null, empty, error states)
- [ ] No negative constraint violations (what NOT to do)

### Security (Invoke Security Skill)
- [ ] No hardcoded secrets
- [ ] Inputs validated, outputs sanitized
- [ ] Dependencies verified (slopsquatting check)

### Testing
- [ ] Tests exist and are meaningful (not just happy path)
- [ ] Tests would catch regression if code breaks

### Quality
- [ ] No duplication with existing utilities
- [ ] Follows project conventions (naming, patterns)
- [ ] Appropriate abstraction level

---

## When to Escalate

| Condition | Escalate To |
|-----------|-------------|
| Security vulnerability | Security team |
| Breaking API change | Tech lead |
| Unclear requirements | Original author |
| Training data uncertainty | Use research tools first |

## When to Pause

- **High ambiguity** — Ask for clarification before reviewing
- **Missing codebase context** — Search more before opining
- **Conflicting requirements** — Flag for author resolution

---

## Detailed References

- `docs/research/reviewer-research-request.md` — Full 2026 review research
- `.claude/skills/security/SKILL.md` — Security review patterns
