Code Review

Code Review Skill

Multi-agent code analysis with parallel reviewers and challenge validation.

Uses explicit subagent dispatch patterns from code-subagents.

Prerequisites

rq (Request Review)

• Required: git
• Optional: gfreview — enables PR integration and line-by-line comments
• Optional: gh — for additional PR management

rs (Respond to Review)

• Required: gfreview — install from https://github.com/martinffx/gfreview
• Required: git

If gfreview is not installed for rs:

Error: rs requires gfreview.

>

Install from: https://github.com/martinffx/gfreview

>

```bash

curl -fsSL https://raw.githubusercontent.com/martinffx/gfreview/main/install.sh | bash

```

Arguments

$0 = command (rq or rs) $1 = target (branch or PR number)

Argument Parsing

Finding PR for Current Branch

gh pr list --head $(git branch --show-current) --json number --jq '.[0].number'

Subagent Architecture

rq (Request Review) Subagents

rs (Respond to Review) Subagents

Dispatch Patterns

Follows code-subagents patterns:

• Parallel dispatch for independent reviewers/discussions
• Sequential dispatch for dependent steps
• Fresh subagent per task — no context pollution
• Skill loading pre-step before each analysis phase
• Error handling: Log failures, continue with partial results

Agent Dispatch

See agents/ for agent definitions.

gfreview Integration

When gfreview is installed:

rq (Request Review)

• Check if PR exists: gfreview list --json --state open
• If PR exists: post findings as line-by-line comments
• If no PR: offer to push branch, create PR, and post findings

rs (Respond to Review)

• Fetch comments: gfreview discussions <id>
• Analyze and plan fixes
• Always ask user before applying fixes or posting responses

Each finding posted as inline comment with severity prefix:

• Critical → Blocker:
• High → Issue:
• Medium → Suggestion:
• Low → Nit:

See gfreview.md for detailed command reference.

References

Workflow Routing

• $0 == rq or no arguments → rq.md
• $0 == rs → rs.md

Context Flow Between Steps

This document describes how data flows between workflow steps in code review.

rq (Request Review) Workflow

┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 1: Get Diff                                                             │
│                                                                              │
│ Input:   <target> (branch name or PR number)                                 │
│ Output:  git_diff, files_changed                                             │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 2: Triage (clerk agent)                                                 │
│                                                                              │
│ Input:   git_diff, files_changed                                             │
│ Output:  triage_result                                                       │
│          {                                                                   │
│            "context": { "language", "framework", "domain" },                 │
│            "reviewers": ["Security", "Correctness", ...],                     │
│            "skills_to_load": ["typescript-testing", "code-security"]         │
│          }                                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 3: Reviewers (parallel general subagents)                               │
│                                                                              │
│ Input:   git_diff, files_changed, triage_result.context,                     │
│          triage_result.skills_to_load                                        │
│                                                                              │
│ Each reviewer receives:                                                       │
│   - context: { language, framework, domain }                                 │
│   - files: files_changed                                                    │
│   - git_diff: full diff                                                    │
│   - skills_to_load: ["typescript-testing", "code-security"]                │
│                                                                              │
│ Output:  reviewer_findings[] (aggregated from all reviewers)                 │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 4: Synthesis (general subagent)                                         │
│                                                                              │
│ Input:   reviewer_findings[]                                                 │
│ Output:  synthesized_findings[]                                              │
│          [                                                                   │
│            { title, severity, locations[], issue, impact, suggestion,         │
│              pre_existing, flag_for_challenge, original_findings[] }         │
│          ]                                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 5: Architect (architect agent)                                          │
│                                                                              │
│ Input:   synthesized_findings[], triage_result.context                       │
│ Output:  architecture_findings[]                                             │
│          [                                                                   │
│            { location, severity, title, issue, impact, suggestion,          │
│              pre_existing }                                                  │
│          ]                                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 6: Challenge (oracle agent)                                             │
│                                                                              │
│ Input:   synthesized_findings[], architecture_findings[]                     │
│ Output:  validated_findings[]                                                │
│          [                                                                   │
│            { title, severity, locations[], issue, impact, suggestion,       │
│              pre_existing, reasoning: { why_flagged, verification,          │
│              evidence, alternative_view } }                                  │
│          ]                                                                   │
│          removed_findings[]                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 7: Final Synthesis (inline)                                             │
│                                                                              │
│ Input:   validated_findings[], removed_findings[]                             │
│ Output:  formatted_review_report                                             │
└─────────────────────────────────────────────────────────────────────────────┘

rs (Respond to Review) Workflow

┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 1-2: Get Target + Fetch Discussions                                     │
│                                                                              │
│ Input:   <pr_number> or current branch                                       │
│ Output:  discussions[]                                                       │
│          [                                                                   │
│            { id, author, file, line, comment, replies[], status }          │
│          ]                                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 3: Triage Discussions (inline)                                          │
│                                                                              │
│ Input:   discussions[]                                                       │
│ Output:  actionable_discussions[]                                             │
│          [                                                                   │
│            { discussion, priority, category }                                │
│          ]                                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 4: Analysis (parallel general subagents)                                │
│                                                                              │
│ Input:   actionable_discussions[], triage_result.context                     │
│                                                                              │
│ Each analysis receives:                                                      │
│   - discussion: { author, file, line, comment, replies, status }            │
│   - code_snippet: relevant code from the file                                │
│   - language: detected from file extension                                   │
│   - skills_to_load: based on file type and category                          │
│                                                                              │
│ Output:  analyses[]                                                          │
│          [                                                                   │
│            { analysis, status_check, suggested_fix, suggested_response }     │
│          ]                                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 5: Validation (general subagent)                                        │
│                                                                              │
│ Input:   analyses[], pr_diff                                                 │
│ Output:  validations[]                                                       │
│          [                                                                   │
│            { discussion_id, fix_valid, concerns[], recommended_action,       │
│              confidence }                                                   │
│          ]                                                                   │
│          conflicts[]                                                         │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 6-10: Synthesize, Show, Confirm, Commit, Post (inline)                  │
│                                                                              │
│ Input:   analyses[], validations[], conflicts[]                              │
│ Output:  applied_fixes[], posted_responses[]                                 │
└─────────────────────────────────────────────────────────────────────────────┘

Data Structures

Triage Result

interface TriageResult {
  context: {
    language: "typescript" | "python" | "go" | "rust" | string;
    framework?: string;
    domain: "web-api" | "frontend" | "database" | "infrastructure" | string;
  };
  reviewers: ReviewerType[];
  skills_to_load: string[];
}

type ReviewerType =
  | "Security"
  | "Performance"
  | "Correctness"
  | "Maintainability"
  | "Architecture"
  | "SecuritySkeptic"
  | "PerformanceOperator"
  | "MaintainabilityPedant"
  | "CorrectnessSkeptic"
  | "ArchitectureArchaeologist";

Finding Structure

interface Finding {
  location: string;        // "file:line"
  severity: "Critical" | "High" | "Medium" | "Low";
  title: string;
  issue: string;
  impact: string;
  suggestion: string;
  pre_existing: boolean;
}

interface ValidatedFinding extends Finding {
  locations: string[];
  reasoning: {
    why_flagged: string;
    verification: string;
    evidence: string;
    alternative_view?: string;
  };
}

Skill Loading by Language

Skill Loading by Category

Error Handling Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│ Subagent Dispatch                                                            │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                    ┌───────────────┴───────────────┐
                    │                               │
                    ▼                               ▼
              Success                          Failure
                    │                               │
                    ▼                               ▼
            Collect results              Log error, continue with
                    │                     partial results
                    ▼                               │
        All successful? ──────Yes──────► Continue to next step
                    │                               │
                    No                              ▼
                    │                      Any successful?
                    ▼                               │
        Continue with partial ◄───Yes────────────────┤
                    │                               │
                    │                               No
                    ▼                               │
        Report error to user                      ▼
        Abort review                          Report error to user
                                              Abort review

gfreview Integration

Installation

https://github.com/martinffx/gfreview

curl -fsSL https://raw.githubusercontent.com/martinffx/gfreview/main/install.sh | bash

Prerequisites

• gfreview CLI installed
• GITHUB_TOKEN or GITLAB_TOKEN environment variable set
• GFREVIEW_FORGE set (github or gitlab, auto-detected from git remote)
• GFREVIEW_PROJECT set (owner/repo, defaults to git remote)

Commands Used

Line-by-Line Comment Posting

Each finding becomes a separate inline comment:

gfreview review start 42

# Finding 1 - Critical:
gfreview review comment 42 --file src/auth/login.ts --line 45 --body "Blocker: Token stored in localStorage

Access token stored in localStorage is vulnerable to XSS attacks.

Use httpOnly cookies or secure session storage."

# Finding 2 - High:
gfreview review comment 42 --file src/auth/middleware.ts --line 12 --body "Issue: Token validated on every request

This adds 50-200ms latency per request.

Cache validation results or use JWT verification."

gfreview review submit 42 --body "Code review complete. Please address blockers and issues before merging."

Severity Prefix Mapping

PR Creation Workflow

CURRENT_BRANCH=$(git branch --show-current)

# Check if PR exists
PR_NUMBER=$(gfreview list --json --state open | jq -r --arg branch "$CURRENT_BRANCH" \
  '.[] | select(.sourceBranch == $branch) | .number')

if [ -z "$PR_NUMBER" ]; then
  # Push branch
  git push -u origin $CURRENT_BRANCH
  
  # Create PR (targets main by default)
  gfreview create --title "My PR Title" --source-branch $CURRENT_BRANCH --target-branch main
  
  # Get new PR number
  PR_NUMBER=$(gfreview list --json --state open | jq -r --arg branch "$CURRENT_BRANCH" \
    '.[] | select(.sourceBranch == $branch) | .number')
fi

# Post review
gfreview review start $PR_NUMBER
# ... comments ...
gfreview review submit $PR_NUMBER

Line Number Rules

From gfreview diff <id> output:

• - prefix = added line → use new file line number
• Space prefix = context line → use new file line number

Error Handling

Output Format

Structured Summary

# Code Review: {module/files}

## Summary
{2-3 sentence overview of changes and overall quality}

## Statistics
- Files reviewed: N
- Findings: N Critical, N High, N Medium, N Low
- Pre-existing: N | Introduced: N

## Critical (Fix before merge)

### {Finding Title}

- **Location**: `file:line`
- **Severity**: Critical
- **Pre-existing**: No
- **Issue**: {What's wrong}
- **Impact**: {Why this matters}
- **Reasoning**:
  <details>
  <summary>Extended reasoning</summary>
  {Detailed explanation of why this was flagged}
  </details>
- **Suggestion**: {How to fix}

## High Priority

### {Finding Title}
{Same structure}

## Medium Priority
{Same structure}

## Low Priority
{Same structure}

## Positive Findings

- {What the code does well}
- {Smart patterns to keep}
- {Good practices observed}

---

Inline Finding Format

For each finding, provide inline comment style:

[{file}:{line}] {Finding Title}
Severity: {Critical/High/Medium/Low}
Pre-existing: {Yes/No}
Issue: {Brief description}
Reasoning: {Why this matters}
Suggestion: {Fix}

---

Severity Definitions

---

Pre-existing vs Introduced

Marking pre-existing:

• Check if the line was modified in the current diff
• If unchanged but flagged, mark as pre-existing
• Pre-existing findings are informational, not blocking

---

Extended Reasoning

Each finding includes a collapsible section with:

1. Why flagged: What triggered the finding (pattern, heuristic, context) 2. Verification: How it was validated (static analysis, pattern match, context) 3. Evidence: Code snippets, references, or examples 4. Alternative view: If uncertain, what else to consider

Example:

<details>
<summary>Extended reasoning</summary>

**Why flagged**: The `query` parameter is directly interpolated into SQL string without parameterization.

**Verification**: Pattern match detected: `f"SELECT * FROM {table}"` - Python f-string in SQL context.

**Evidence**: 

query = f"SELECT * FROM users WHERE id = {user_id}" # Line 42

**Alternative view**: If using a query builder or ORM, check if it handles escaping internally.
</details>

---

Example Output

# Code Review: src/auth/login.ts

## Summary
Implements OAuth login flow with token refresh. Generally well-structured with proper error handling. One security concern around token storage and a performance issue with token validation on every request.

## Statistics
- Files reviewed: 1
- Findings: 1 Critical, 1 High, 0 Medium, 2 Low
- Pre-existing: 1 | Introduced: 3

## Critical (Fix before merge)

### Token stored in localStorage

- **Location**: `src/auth/login.ts:45`
- **Severity**: Critical
- **Pre-existing**: No
- **Issue**: Access token stored in localStorage, vulnerable to XSS
- **Impact**: Any XSS vulnerability exposes user tokens
- **Reasoning**:
  <details>
  <summary>Extended reasoning</summary>
  
  **Why flagged**: localStorage is accessible to any JavaScript on the page.
  
  **Verification**: Direct localStorage API usage detected.
  
  **Evidence**:

localStorage.setItem('accessToken', token); // Line 45

  
  **Alternative view**: If using httpOnly cookies is not possible, consider short-lived tokens with refresh rotation.
  </details>
- **Suggestion**: Use httpOnly cookies or secure session storage

## High Priority

### Token validation on every request

- **Location**: `src/auth/middleware.ts:12`
- **Severity**: High
- **Pre-existing**: Yes
- **Issue**: Token validated against auth server on every request
- **Impact**: Adds 50-200ms latency per request

## Low Priority

### Missing JSDoc on public function

- **Location**: `src/auth/login.ts:23`
- **Severity**: Low
- **Pre-existing**: No
- **Issue**: `validateToken` lacks documentation

### Inconsistent naming: userId vs user_id

- **Location**: `src/auth/login.ts:67`
- **Severity**: Low
- **Pre-existing**: Yes
- **Issue**: Mixed snake_case and camelCase in same file

## Positive Findings

- Clean separation of OAuth flow into dedicated functions
- Proper error handling with typed error classes
- Token refresh logic handles edge cases well

---

Implementation Notes

1. Skills to load are determined by Triage based on detected language/framework 2. Pre-existing detection requires git blame check (not just diff) 3. Extended reasoning should be collapsible in markdown renderers 4. Positive findings help balance the review tone

Reviewer Definitions

Subagent Invocation Pattern

All reviewers are dispatched as parallel subagents following code-subagents patterns.

Uses: general subagent - One per reviewer, dispatched concurrently

Task Tool Invocation Template

# Dispatch ONE subagent per selected reviewer
subagent_type: general
description: "{ReviewerName} code review"
prompt: |
  You are a {ReviewerName} analyzing code for {focus_area}.

  CONTEXT:
  - Language: {language}
  - Framework: {framework}
  - Files changed: {files}

  **PRE-STEP: Load Relevant Skills**
  Before reviewing, load these skills:
  {skills_to_load}

  Use the `skill` tool to load each skill.

  GIT DIFF:

{git_diff}

  {PROMPT_TEMPLATE_FROM_BELOW}

  Return findings as JSON:
  {
    "findings": [
      {
        "location": "file:line",
        "severity": "Critical|High|Medium|Low",
        "title": "Brief finding name",
        "issue": "What's wrong",
        "impact": "Why this matters",
        "suggestion": "How to fix",
        "pre_existing": true|false
      }
    ]
  }

Parallel Dispatch Pattern

Spawn all reviewer subagents simultaneously:
├── Security Reviewer ───→ findings.json
├── Correctness Reviewer ───→ findings.json
├── Performance Reviewer ───→ findings.json
└── (etc.)

Error Handling

Per code-subagents:

• Subagent timeout/failure → Log error, continue with others
• All subagents fail → Report error to user, abort review
• Partial success → Use findings from successful reviewers

---

Concern-Type Reviewers

Security Reviewer

Prompt Template:

You are a Security Reviewer analyzing code for security vulnerabilities.

Context:
- Files: {files}
- Git diff: {git_diff}
- Loaded skills: {skills}

Focus areas:
- Authentication and authorization flaws
- Injection vulnerabilities (SQL, command, XSS)
- Secrets in code (API keys, passwords, tokens)
- Surface area exposure
- Input validation gaps

Output findings in this format:
- **Location**: file:line
- **Severity**: Critical/High/Medium/Low
- **Issue**: What's wrong
- **Impact**: Why this matters
- **Suggestion**: How to fix
- **Pre-existing**: Yes/No (check if existed before this PR)

Loads: code-security (if exists)

---

Performance Reviewer

Prompt Template:

You are a Performance Reviewer analyzing code for performance issues.

Context:
- Files: {files}
- Git diff: {git_diff}
- Loaded skills: {skills}

Focus areas:
- Hot paths and bottlenecks
- Memory allocation patterns
- N+1 query problems
- Unnecessary computation
- Caching opportunities

Output findings in this format:
- **Location**: file:line
- **Severity**: Critical/High/Medium/Low
- **Issue**: What's wrong
- **Impact**: Performance cost
- **Suggestion**: How to fix
- **Pre-existing**: Yes/No

Loads: code-perf (if exists)

---

Correctness Reviewer

Prompt Template:

You are a Correctness Reviewer analyzing code for logic errors.

Context:
- Files: {files}
- Git diff: {git_diff}
- Loaded skills: {skills}

Focus areas:
- Logic errors and edge cases
- Error handling completeness
- Type soundness
- Null/undefined handling
- Boundary conditions

Output findings in this format:
- **Location**: file:line
- **Severity**: Critical/High/Medium/Low
- **Issue**: What's wrong
- **Impact**: What breaks
- **Suggestion**: How to fix
- **Pre-existing**: Yes/No

Loads: Language-specific skills (typescript-testing, python-testing, etc.)

---

Maintainability Reviewer

Prompt Template:

You are a Maintainability Reviewer analyzing code quality.

Context:
- Files: {files}
- Git diff: {git_diff}
- Loaded skills: {skills}

Focus areas:
- Naming clarity
- Code complexity (cyclomatic, cognitive)
- Test coverage gaps
- Coupling and cohesion
- DRY violations

Output findings in this format:
- **Location**: file:line
- **Severity**: Critical/High/Medium/Low
- **Issue**: What's wrong
- **Impact**: Maintainability cost
- **Suggestion**: How to fix
- **Pre-existing**: Yes/No

Loads: Testing skills, language-specific patterns

---

Architecture Reviewer

Prompt Template:

You are an Architecture Reviewer analyzing structural issues.

Context:
- Files: {files}
- Git diff: {git_diff}
- Loaded skills: {skills}

Focus areas:
- Boundary violations
- Responsibility leakage
- Dependency direction
- Layer separation
- SOLID violations

Output findings in this format:
- **Location**: file:line
- **Severity**: Critical/High/Medium/Low
- **Issue**: What's wrong
- **Impact**: Architectural debt
- **Suggestion**: How to fix
- **Pre-existing**: Yes/No

Loads: oracle-architect, language architecture skills

---

Persona Reviewers

Pedant Reviewer

Prompt Template:

You are a Pedant Reviewer - nitpicky by design.

Context:
- Files: {files}
- Git diff: {git_diff}
- Loaded skills: {skills}

Focus areas:
- Style consistency
- Naming conventions
- Documentation gaps
- Formatting issues
- Code organization

Note: Flag minor issues as Low severity. Be thorough but not annoying.

Output findings in this format:
- **Location**: file:line
- **Severity**: Low (pedantic findings are rarely higher)
- **Issue**: What's inconsistent
- **Suggestion**: How to fix
- **Pre-existing**: Yes/No

Loads: Language-specific lint/style skills

---

Skeptic Reviewer

Prompt Template:

You are a Skeptic Reviewer - you assume the code will be misused.

Context:
- Files: {files}
- Git diff: {git_diff}
- Loaded skills: {skills}

Focus areas:
- "What happens when this fails?"
- Error handling gaps
- Edge cases no one thinks about
- Assumptions that might not hold
- Defensive coding gaps

Output findings in this format:
- **Location**: file:line
- **Severity**: Critical/High/Medium/Low
- **Issue**: What could go wrong
- **Impact**: Failure scenario
- **Suggestion**: Defensive fix
- **Pre-existing**: Yes/No

---

Archaeologist Reviewer

Prompt Template:

You are an Archaeologist Reviewer - you read git blame mentally.

Context:
- Files: {files}
- Git diff: {git_diff}
- Loaded skills: {skills}

Focus areas:
- Code that looks like it survived from an old design
- Patterns that don't match current conventions
- TODOs and FIXMEs older than 6 months
- Dead code paths
- Outdated comments

Output findings in this format:
- **Location**: file:line
- **Severity**: Low/Medium (archaeological finds are rarely critical)
- **Issue**: What's outdated
- **Context**: Historical pattern
- **Suggestion**: Modernize or remove
- **Pre-existing**: Yes (always)

---

Operator Reviewer

Prompt Template:

You are an Operator Reviewer - you think about production reality.

Context:
- Files: {files}
- Git diff: {git_diff}
- Loaded skills: {skills}

Focus areas:
- Logging completeness
- Observability gaps
- What happens at 3am when this breaks
- Runbook needed?
- Monitoring blind spots

Output findings in this format:
- **Location**: file:line
- **Severity**: Medium/High (operational issues hurt in prod)
- **Issue**: Operational gap
- **Impact**: What happens at 3am
- **Suggestion**: How to fix
- **Pre-existing**: Yes/No

---

New Hire Reviewer

Prompt Template:

You are a New Hire Reviewer - you flag anything needing explanation.

Context:
- Files: {files}
- Git diff: {git_diff}
- Loaded skills: {skills}

Focus areas:
- Code that needs a comment to understand
- Implicit knowledge assumed
- Unexplained magic numbers
- Non-obvious patterns
- Onboarding friction points

Output findings in this format:
- **Location**: file:line
- **Severity**: Low/Medium (readability issues)
- **Issue**: What's unclear
- **Impact**: Time to understand
- **Suggestion**: Add comment or refactor
- **Pre-existing**: Yes/No

---

Hybrid Reviewers

Security + Skeptic (SecuritySkeptic)

Prompt Template:

You are a Security Skeptic - security findings challenged with failure scenarios.

Context:
- Files: {files}
- Git diff: {git_diff}
- Loaded skills: {skills}

Focus areas:
- Security vulnerabilities with "what happens when exploited" lens
- Attack vectors no one considers
- Defense in depth gaps
- "That would never happen" assumptions

Combine security rigor with pessimistic failure thinking.

Output findings in this format:
- **Location**: file:line
- **Severity**: Critical/High/Medium/Low
- **Issue**: What's wrong
- **Impact**: Why this matters
- **Suggestion**: How to fix
- **Pre-existing**: Yes/No

---

### Maintainability + Pedant (MaintainabilityPedant)

**Prompt Template:**

You are a Maintainability Pedant - style and quality with pedantic precision.

Context:

• Files: {files}
• Git diff: {git_diff}
• Loaded skills: {skills}

Focus areas:

• Every naming inconsistency
• Every documentation gap
• Every complexity issue
• Thorough code quality audit

Be thorough. Flag everything, but mark appropriately.

Output findings in this format:

• Location: file:line
• Severity: Low/Medium (pedantic findings are rarely critical)
• Issue: What's inconsistent
• Suggestion: How to fix
• Pre-existing: Yes/No

---

### Correctness + Skeptic (CorrectnessSkeptic)

**Prompt Template:**

You are a Correctness Skeptic - logic errors with "what if this fails" lens.

Context:

• Files: {files}
• Git diff: {git_diff}
• Loaded skills: {skills}

Focus areas:

• Logic errors with failure scenarios
• Edge cases combined with pessimistic assumptions
• "This should never happen" cases
• Type soundness with runtime failures in mind

Output findings in this format:

• Location: file:line
• Severity: Critical/High/Medium/Low
• Issue: What's wrong
• Impact: What breaks
• Suggestion: How to fix
• Pre-existing: Yes/No

---

### Architecture + Archaeologist (ArchitectureArchaeologist)

**Prompt Template:**

You are an Architecture Archaeologist - boundary issues with historical context.

Context:

• Files: {files}
• Git diff: {git_diff}
• Loaded skills: {skills}

Focus areas:

• Architectural violations that might be legacy
• Patterns that don't match current architecture
• Historical tech debt
• Evolution opportunities

Combine architectural rigor with historical awareness.

Output findings in this format:

• Location: file:line
• Severity: Medium/High (architectural issues compound over time)
• Issue: What's wrong
• Impact: Architectural debt
• Suggestion: How to fix
• Pre-existing: Yes/No

---

### Performance + Operator (PerformanceOperator)

**Prompt Template:**

You are a Performance Operator - performance with production reality.

Context:

• Files: {files}
• Git diff: {git_diff}
• Loaded skills: {skills}

Focus areas:

• Performance issues that matter in prod
• N+1 queries at scale
• Memory leaks over time
• Resource exhaustion scenarios
• Real-world performance costs

Combine performance analysis with operational experience.

Output findings in this format:

• Location: file:line
• Severity: High (performance hurts at scale)
• Issue: What's wrong
• Impact: Performance cost at scale
• Suggestion: How to fix
• Pre-existing: Yes/No

---

## Skill Loading Guidelines

Each reviewer should load relevant skills before reviewing:

| Reviewer Type | Skills to Load |
|---------------|----------------|
| Security | `code-security` |
| Performance | `code-perf` |
| Correctness | Language-specific (`typescript-testing`, `python-testing`, etc.) |
| Maintainability | Testing skills |
| Architecture | `oracle-architect` |
| Pedant | Language-specific lint/style skills |
| Skeptic | None (mindset-based) |
| Archaeologist | None (context-based) |
| Operator | None (experience-based) |
| New Hire | None (fresh-eyes-based) |
| Hybrid | Combine constituent reviewers' skills |

---

## Complete Example: Dispatching Reviewer Subagents

Given triage output:

{ "context": { "language": "typescript", "framework": "fastify" }, "reviewers": ["Security", "Correctness", "PerformanceOperator"], "files": ["src/auth/login.ts", "src/middleware/auth.ts"] }

### Dispatch Reviewer Subagents (Parallel)

Each subagent loads its own relevant skills before reviewing:

**Security Reviewer:**

subagent_type: general description: "Security review of PR" prompt: | You are a Security Reviewer analyzing code for security vulnerabilities.

CONTEXT:

• Language: typescript
• Framework: fastify
• Files: src/auth/login.ts, src/middleware/auth.ts

GIT DIFF:

  {paste diff here}

YOUR FIRST TASK - LOAD SKILLS: As a Security Reviewer, you should load relevant skills before reviewing: 1. Load skill: code-security - Use the skill tool 2. Load skill: typescript-testing (if available) - Use the skill tool

These skills contain security patterns and TypeScript testing guidance that will help you identify issues.

Focus areas after loading skills:

• Authentication and authorization flaws
• Injection vulnerabilities (SQL, command, XSS)
• Secrets in code (API keys, passwords, tokens)
• Surface area exposure
• Input validation gaps

Return findings as JSON: { "findings": [ { "location": "src/auth/login.ts:45", "severity": "Critical", "title": "Token stored in localStorage", "issue": "Access token stored in localStorage, vulnerable to XSS", "impact": "Any XSS vulnerability exposes user tokens", "suggestion": "Use httpOnly cookies or secure session storage", "pre_existing": false } ] }

**Correctness Reviewer:**

subagent_type: general description: "Correctness review of PR" prompt: | You are a Correctness Reviewer analyzing code for logic errors.

CONTEXT:

• Language: typescript
• Framework: fastify
• Files: src/auth/login.ts, src/middleware/auth.ts

GIT DIFF:

  {paste diff here}

YOUR FIRST TASK - LOAD SKILLS: As a Correctness Reviewer, you should load relevant skills before reviewing: 1. Load skill: typescript-testing - Use the skill tool

This skill contains TypeScript testing patterns and correctness guidance.

Focus areas after loading skills:

• Logic errors and edge cases
• Error handling completeness
• Type soundness
• Null/undefined handling
• Boundary conditions

Return findings as JSON: { "findings": [...] }

**PerformanceOperator Reviewer:**

subagent_type: general description: "Performance review of PR" prompt: | You are a Performance Operator - performance with production reality.

CONTEXT:

• Language: typescript
• Framework: fastify
• Files: src/auth/login.ts, src/middleware/auth.ts

GIT DIFF:

  {paste diff here}

YOUR FIRST TASK - LOAD SKILLS: As a PerformanceOperator Reviewer, you should load relevant skills before reviewing: 1. Load skill: code-perf (if available) - Use the skill tool 2. Load skill: typescript-testing (if available) - Use the skill tool

Focus areas after loading skills:

• Performance issues that matter in prod
• N+1 queries at scale
• Memory leaks over time
• Resource exhaustion scenarios
• Real-world performance costs

Return findings as JSON: { "findings": [...] }

### Aggregate Results

Collect all findings from parallel subagents:

all_findings = []

Security results

if security_result.success: all_findings.extend(security_result.findings) else: log.error(f"Security reviewer failed: {security_result.error}")

Correctness results

if correctness_result.success: all_findings.extend(correctness_result.findings) else: log.error(f"Correctness reviewer failed: {correctness_result.error}")

PerformanceOperator results

if perf_result.success: all_findings.extend(perf_result.findings) else: log.error(f"Performance reviewer failed: {perf_result.error}")

Continue with synthesis even if some reviewers failed

if not all_findings: report_error("All reviewers failed") return

### Key Points

1. **Parallel dispatch** — All reviewers run simultaneously
2. **Fresh subagent per reviewer** — No context pollution between reviewers
3. **Self-loading skills** — Each subagent loads its own relevant skills using the `skill` tool
4. **Error isolation** — One reviewer failing doesn't block others
5. **Structured output** — JSON format for easy aggregation

Request Review (rq) Workflow

Overview

This workflow: 1. Checks for gfreview availability 2. Gets diff (git diff by default, gfreview if PR number given) 3. Triage Subagent - Analyzes diff, selects reviewers, identifies skills to load 4. Reviewer Subagents (parallel) - Each selected reviewer analyzes code 5. Synthesis Subagent - Deduplicates findings 6. Architect Subagent - Architecture review 7. Challenge Subagent - Validates findings 8. Handles output (terminal + optional gfreview PR integration)

---

Step 0: Check Prerequisites

Check if gfreview is available:

which gfreview 2>/dev/null && gfreview --version

• HAS_GFREVIEW=true: Enable full PR integration
• HAS_GFREVIEW=false: Continue with git diff only (no PR posting)

---

Step 1: Get Diff

Default: git diff to main

git diff main

If --target <branch> specified:

git diff <branch>

With PR number

If PR number provided:

• HAS_GFREVIEW=true: Use gfreview diff <id>
• HAS_GFREVIEW=false: Show error, fallback to git diff

If gfreview not installed but PR number given:

PR review requires gfreview.

Install: curl -fsSL https://raw.githubusercontent.com/martinffx/gfreview/main/install.sh | bash

Falling back to git diff main...

---

Step 2: Triage Subagent

Purpose: Analyze diff to determine context, select reviewers, identify skills to load.

Uses: clerk agent (minimax-m2.5) - See agents/clerk.md

Subagent Invocation

subagent_type: clerk
description: "Triage diff for code review"
prompt: |
  Analyze this code diff to determine review needs.

  FILES: {files_changed}
  DIFF: {git_diff}

  Tasks:
  1. Detect the primary language and framework
  2. Identify the domain (web API, frontend, database, etc.)
  3. Select 3-5 reviewers from this list based on what's in the diff:
     - Security (auth, secrets, injection risks)
     - Performance (hot paths, queries, algorithms)
     - Correctness (logic, types, error handling)
     - Maintainability (naming, complexity, tests)
     - Architecture (boundaries, layers, SOLID)
     - SecuritySkeptic (security + failure scenarios)
     - PerformanceOperator (performance at scale)
     - MaintainabilityPedant (quality + precision)
  4. **Identify skills to load** based on detected language/framework:
     - TypeScript → typescript-testing, typescript-fastify (if fastify framework)
     - Python → python-testing, python-fastapi (if fastapi framework)
     - Security concerns → code-security
     - Performance concerns → code-perf

  Return ONLY valid JSON (no markdown, no code blocks):
  {
    "context": {
      "language": "typescript|python|go|...",
      "framework": "react|fastapi|...",
      "domain": "web-api|frontend|database|..."
    },
    "reviewers": ["Security", "Correctness"],
    "skills_to_load": ["typescript-testing", "code-security"]
  }

Expected Output

{
  "context": { "language": "typescript", "framework": "fastify", "domain": "web-api" },
  "reviewers": ["Security", "Correctness", "PerformanceOperator"],
  "skills_to_load": ["typescript-testing", "code-security"]
}

---

Step 3: Reviewer Subagents (Parallel)

Purpose: Each selected reviewer analyzes the code from their specialty perspective.

Uses: general subagent - One per reviewer, dispatched concurrently

Pattern: Spawn one subagent per reviewer concurrently (parallel execution).

Skill Loading Pre-Step

Before dispatching reviewers, the detected skills are passed to each reviewer:

{
  "skills_to_load": ["typescript-testing", "code-security"]
}

Subagent Invocation (One per Reviewer)

subagent_type: general
description: "Security review of code diff"
prompt: |
  You are a Security Reviewer analyzing code for security vulnerabilities.

  CONTEXT:
  - Language: {language}
  - Framework: {framework}
  - Files: {files}

  **PRE-STEP: Load Relevant Skills**
  Before reviewing, load these skills:
  {skills_to_load}

  Use the `skill` tool to load each skill.

  DIFF:
  {git_diff}

  Focus areas:
  - Authentication and authorization flaws
  - Injection vulnerabilities (SQL, command, XSS)
  - Secrets in code (API keys, passwords, tokens)
  - Surface area exposure
  - Input validation gaps

  Return findings as JSON array. For each finding:
  {
    "findings": [
      {
        "location": "file:line",
        "severity": "Critical|High|Medium|Low",
        "title": "Brief finding name",
        "issue": "What's wrong",
        "impact": "Why this matters",
        "suggestion": "How to fix",
        "pre_existing": true|false
      }
    ]
  }

  If no findings, return {"findings": []}

Parallel Execution

Invoke all reviewer subagents simultaneously:

Concurrent invocations:
├── Security Reviewer
├── Correctness Reviewer
├── PerformanceOperator Reviewer
└── (etc. based on triage output)

Error Handling

• If a subagent fails/times out: Log error, continue with other reviewers
• If all subagents fail: Report error to user, abort review
• Partial results: Use findings from successful reviewers only

Aggregating Results

Collect findings from all reviewer subagents:

all_findings = []
for reviewer in reviewers:
    result = await reviewer_subagent(reviewer)
    if result.success:
        all_findings.extend(result.findings)

---

Step 4: Synthesis Subagent (First Pass)

Purpose: Group, deduplicate, and assign initial severity.

Uses: general subagent

Subagent Invocation

subagent_type: general
description: "Synthesize code review findings"
prompt: |
  Synthesize these code review findings from multiple reviewers.

  RAW FINDINGS:
  {all_findings_json}

  Tasks:
  1. Deduplicate findings that refer to the same issue
  2. Flag potential false positives
  3. Assign initial severity based on consensus
  4. Group by severity (Critical, High, Medium, Low)

  Return JSON:
  {
    "synthesized": [
      {
        "title": "Finding title",
        "severity": "Critical|High|Medium|Low",
        "locations": ["file:line", "file:line"],
        "issue": "Consolidated issue description",
        "impact": "Why this matters",
        "suggestion": "How to fix",
        "pre_existing": true|false,
        "flag_for_challenge": true|false,
        "original_findings": ["Reviewer: finding summary"]
      }
    ]
  }

---

Step 5: Architect Subagent

Purpose: Review architecture-specific concerns.

Uses: architect agent (kimi-k2.5) - See agents/architect.md

Subagent Invocation

subagent_type: architect
description: "Architecture review of code diff"
prompt: |
  You are an Architecture Reviewer analyzing structural issues.

  CONTEXT:
  - Language: {language}
  - Framework: {framework}
  - Files: {files}

  SYNTHESIZED FINDINGS:
  {synthesized_findings_json}

  **PRE-STEP: Load Relevant Skills**
  Before reviewing, load:
  - Use `skill` tool to load: oracle-architect

  Focus areas:
  - Boundary violations
  - Responsibility leakage
  - Dependency direction
  - Layer separation
  - SOLID violations
  - Data model design
  - API contract design

  Return findings as JSON:
  {
    "architecture_findings": [
      {
        "location": "file:line",
        "severity": "High|Medium",
        "title": "Architecture Finding",
        "issue": "What's wrong",
        "impact": "Architectural debt",
        "suggestion": "How to fix",
        "pre_existing": true|false
      }
    ]
  }

---

Step 6: Challenge Subagent

Purpose: Validate findings by challenging assumptions.

Uses: oracle agent (glm-5) - See agents/oracle.md

Subagent Invocation

subagent_type: oracle
description: "Challenge code review findings"
prompt: |
  Challenge these code review findings critically using sequential-thinking.

  ALL FINDINGS (includes synthesized + architecture):
  {all_findings_json}

  **PRE-STEP: Load Relevant Skills**
  Before challenging, load:
  - Use `skill` tool to load: oracle-challenge

  For each flagged finding, use `mcp__sequential-thinking__sequentialthinking` to analyze:
  1. Is this handled elsewhere in the codebase?
  2. Is this the correct place for this concern?
  3. Is this a valid concern or a false positive?
  4. What evidence supports or refutes this finding?
  5. What are alternative perspectives to consider?

  Return JSON with validated findings:
  {
    "validated": [
      {
        "title": "Finding title",
        "severity": "Critical|High|Medium|Low",
        "locations": ["file:line"],
        "issue": "Issue description",
        "impact": "Impact explanation",
        "suggestion": "Fix suggestion",
        "pre_existing": true|false,
        "reasoning": {
          "why_flagged": "What triggered the finding",
          "verification": "How it was validated",
          "evidence": "Code snippets or references",
          "alternative_view": "Other perspectives to consider"
        }
      }
    ],
    "removed": ["Finding titles that were false positives"]
  }

---

Step 7: Final Synthesis

Purpose: Produce final report with extended reasoning sections.

This step is done inline (no subagent needed) - format the validated findings into the output structure defined in output.md.

---

Step 8: Handle Findings Output

Terminal Output (always)

Display findings in terminal per output.md.

---

If gfreview NOT Installed

Output to terminal only.

Install gfreview to enable PR integration:

curl -fsSL https://raw.githubusercontent.com/martinffx/gfreview/main/install.sh | bash

---

If gfreview IS Installed

Check for existing PR

CURRENT_BRANCH=$(git branch --show-current)
TARGET_BRANCH=${TARGET_BRANCH:-main}

PR_NUMBER=$(gfreview list --json --state open | jq -r --arg branch "$CURRENT_BRANCH" \
  '.[] | select(.sourceBranch == $branch) | .number')

Case 1: PR Exists

Found PR #{PR_NUMBER} for branch '{CURRENT_BRANCH}'.
Post {N} findings as line-by-line comments? [y/N]

If yes:

gfreview review start $PR_NUMBER

# For each finding:
gfreview review comment $PR_NUMBER --file <path> --line <n> --body "<severity>: <title>

<issue>

<impact>

<suggestion>"

gfreview review submit $PR_NUMBER --body "Code review complete. Please address blockers and issues before merging."

Case 2: No PR Exists

No PR found for branch '{CURRENT_BRANCH}'.
Create PR and post findings? [y/N]

If yes:

# Push branch to remote
git push -u origin $CURRENT_BRANCH

# Create PR (targets main by default)
gfreview create --title "<title>" --source-branch $CURRENT_BRANCH --target-branch main

# Get new PR number
PR_NUMBER=$(gfreview list --json --state open | jq -r --arg branch "$CURRENT_BRANCH" \
  '.[] | select(.sourceBranch == $branch) | .number')

# Post findings line-by-line
gfreview review start $PR_NUMBER
# ... comments ...
gfreview review submit $PR_NUMBER --body "Code review complete."

---

Subagent Summary

Respond to Review (rs) Workflow

Overview

This workflow responds to PR review feedback.

Requires gfreview.

Steps: 0. Check gfreview installed 1. Get target PR 2. Fetch discussions 3. Triage discussions (inline) 4. Analysis Subagents (parallel) 5. Validation Subagent 6. Confirm fixes with user [y/N/a] 7. Commit and push 8. Post responses [y/N] 9. Summary

---

Step 0: Check Prerequisites

rs requires gfreview.

which gfreview 2>/dev/null && gfreview --version

If not installed:

Error: rs requires gfreview.

Install from: https://github.com/martinffx/gfreview

curl -fsSL https://raw.githubusercontent.com/martinffx/gfreview/main/install.sh | bash

After installation, run `rs` again.

Abort workflow if gfreview not available.

---

Step 1: Get Target

• If $1 provided: use as PR number
• If no $1: find PR for current branch

gh pr list --head $(git branch --show-current) --json number --jq '.[0].number'

---

Step 2: Fetch Discussions

gfreview discussions <id>

Parse discussion thread structure:

• Main comment
• Reply thread
• Resolution status
• Author

---

Step 3: Triage Discussions

Group and prioritize (done inline, no subagent):

• Skip already-resolved discussions
• Group related comments (same issue, different files)
• Prioritize: Blocker > Issue > Suggestion > Nit
• Identify quick wins vs complex fixes

---

Step 4: Analysis Subagents (Parallel)

Purpose: Analyze each discussion thread and suggest fixes.

Uses: general subagent - One per discussion, dispatched concurrently

Pattern: Spawn one subagent per actionable discussion concurrently.

Subagent Invocation (One per Discussion)

subagent_type: general
description: "Analyze PR discussion thread"
prompt: |
  Analyze this code review discussion and suggest how to address it.

  DISCUSSION:
  - Author: @{author}
  - File: {file_path}
  - Line: {line_number}
  - Comment: {main_comment}
  - Thread replies: {replies}
  - Current resolution status: {status}

  RELEVANT CODE:

{code_snippet}

  **PRE-STEP: Load Relevant Skills**
  Before analyzing, load skills based on file type and discussion topic:
  - Use `skill` tool to load: {language}:testing (if available)
  - Use `skill` tool to load: code-security (if security-related)
  - Use `skill` tool to load: code-perf (if performance-related)
  - Use `skill` tool to load: oracle-architect (if architecture-related)

  Tasks:
  1. Load relevant skills using the `skill` tool
  2. Understand what the reviewer is asking for
  3. Identify the specific issue or suggestion
  4. Determine the exact code location that needs changes
  5. Check if this has already been addressed in recent commits (check git log)
  6. Suggest a concrete fix or appropriate response

  CRITICAL: Be specific. Include exact file paths, line numbers, and code changes.

  Return JSON:
  {
    "analysis": {
      "understanding": "Clear description of what reviewer wants",
      "issue_type": "bug|suggestion|question|style|documentation",
      "severity": "Blocker|Issue|Suggestion|Nit",
      "location": {
        "file": "exact/path/to/file.ts",
        "line": 42,
        "snippet": "relevant code"
      }
    },
    "status_check": {
      "already_addressed": true|false,
      "addressed_in_commit": "abc123 (if applicable)"
    },
    "suggested_fix": {
      "applicable": true|false,
      "description": "What change to make",
      "before": "original code",
      "after": "fixed code"
    },
    "suggested_response": {
      "text": "Response to post on PR",
      "tone": "agree|disagree|question|acknowledge"
    }
  }

Parallel Execution Pattern

Concurrent invocations (one per actionable discussion):
├── Discussion #1: "Missing validation on line 45"
├── Discussion #2: "Consider using const instead of let"
├── Discussion #3: "This could cause N+1 query"
└── Discussion #4: "Typo in comment"

Error Handling (per code-subagents)

• If a subagent fails/times out: Log error, continue with other discussions
• If all subagents fail: Report error to user
• Partial results: Use analyses from successful subagents only

---

Step 5: Validation Subagent

Purpose: Validate that suggested fixes don't introduce problems.

Subagent Invocation

subagent_type: general
description: "Validate suggested code review fixes"
prompt: |
  Validate these suggested fixes for code review feedback.

  SUGGESTED FIXES:
  {all_analyses_json}

  FULL DIFF CONTEXT:
  {pr_diff}

  Tasks:
  For each suggested fix:
  1. Does this actually address the issue raised?
  2. Could this introduce new problems or regressions?
  3. Is the response tone appropriate and professional?
  4. Are there any edge cases not considered?

  Return JSON:
  {
    "validations": [
      {
        "discussion_id": "identifier",
        "fix_valid": true|false,
        "concerns": ["List any concerns or risks"],
        "recommended_action": "apply|skip|modify",
        "confidence": "high|medium|low"
      }
    ],
    "conflicts": [
      {
        "between": ["fix_a", "fix_b"],
        "description": "How they conflict"
      }
    ]
  }

---

Step 6: Synthesize (Inline)

Merge analyses and validations (done inline):

• Dedupe overlapping fixes
• Group by file
• Order by priority

---

Step 7: Show Analysis and Confirm Fixes

Show Analysis

Present each discussion:

Discussion #1 with @{author}:
> {main_comment}

Thread: {replies if any}

Analysis:
- Understanding: {understanding}
- Issue: {issue_type}
- Suggested fix: {description}
- Validation: {concerns if any}

Confirm Fixes with User

Always ask user before applying fixes.

For each suggested fix:

{file}:{line} - {suggestion}

Apply this fix? [y/N/a]
- y: Apply this fix only
- N: Skip this fix
- a: Apply all remaining fixes without asking

CRITICAL: Never apply changes without user confirmation.

If a selected: Set flag APPLY_ALL=true, skip remaining confirmations.

---

Step 8: Commit and Push

If fixes were applied:

Commit these changes? [y/N]

If yes:

git add <files>
git commit -m "fix: <summary of changes> (review feedback)"
git push

If APPLY_ALL=true: Commit automatically without asking.

---

Step 9: Post Responses

Post {N} responses to PR comments? [y/N]

If yes:

gfreview review start <id>

# For each addressed comment:
gfreview review comment <id> --file <path> --line <n> --body "Response: <message>"

gfreview review submit <id> --body "Addressed review feedback."

---

Step 10: Summary

Show summary of actions taken:

=== Review Response Summary ===
Fixes applied: N
Responses posted: N
Remaining discussions: N

---

Subagent Summary