Ring Requesting Code Review

Code Review (Gate 4)

Overview

Dispatch all six reviewer subagents in parallel for fast, comprehensive feedback:

1. ring:code-reviewer - Architecture, design patterns, code quality
2. ring:business-logic-reviewer - Domain correctness, business rules, edge cases
3. ring:security-reviewer - Vulnerabilities, authentication, OWASP risks
4. ring:test-reviewer - Test quality, coverage, edge cases, anti-patterns
5. ring:nil-safety-reviewer - Nil/null pointer safety for Go and TypeScript
6. ring:consequences-reviewer - Ripple effects, caller chain impact, downstream consequences

Core principle: All 6 reviewers run simultaneously in a single message with 6 Task tool calls.

CRITICAL: Role Clarification

This skill ORCHESTRATES. Reviewer Agents REVIEW.

Step 1: Gather Context (Auto-Detect if Not Provided)

This skill supports TWO modes:
1. WITH INPUTS: Called by any skill/user that provides structured inputs (unit_id, base_sha, etc.)
2. STANDALONE: Called directly without inputs - auto-detects everything from git

FOR EACH INPUT, check if provided OR auto-detect:

1. unit_id:
   IF provided → use it
   ELSE → generate: "review-" + timestamp (e.g., "review-20241222-143052")

2. base_sha:
   IF provided → use it
   ELSE → Execute: git merge-base HEAD main
   IF git fails → Execute: git rev-parse HEAD~10 (fallback to last 10 commits)

3. head_sha:
   IF provided → use it
   ELSE → Execute: git rev-parse HEAD

4. implementation_files:
   IF provided → use it
   ELSE → Execute: git diff --name-only [base_sha] [head_sha]

5. implementation_summary:
   IF provided → use it
   ELSE → Execute: git log --oneline [base_sha]..[head_sha]
   Format as: "Changes: [list of commit messages]"

6. requirements:
   IF provided → use it
   ELSE → Set to: "Infer requirements from code changes and commit messages"
   (Reviewers will analyze code to understand intent)

AFTER AUTO-DETECTION, display context:
┌─────────────────────────────────────────────────────────────────┐
│ 📋 CODE REVIEW CONTEXT                                          │
├─────────────────────────────────────────────────────────────────┤
│ Unit ID: [unit_id]                                              │
│ Base SHA: [base_sha]                                            │
│ Head SHA: [head_sha]                                            │
│ Files Changed: [count] files                                    │
│ Commits: [count] commits                                        │
│                                                                 │
│ Dispatching 6 reviewers in parallel...                          │
└─────────────────────────────────────────────────────────────────┘

Step 2: Initialize Review State

review_state = {
  unit_id: [from input],
  base_sha: [from input],
  head_sha: [from input],
  reviewers: {
    code_reviewer: {verdict: null, issues: []},
    business_logic_reviewer: {verdict: null, issues: []},
    security_reviewer: {verdict: null, issues: []},
    test_reviewer: {verdict: null, issues: []},
    nil_safety_reviewer: {verdict: null, issues: []},
    consequences_reviewer: {verdict: null, issues: []}
  },
  aggregated_issues: {
    critical: [],
    high: [],
    medium: [],
    low: [],
    cosmetic: []
  },
  iterations: 0,
  max_iterations: 3
}

Step 2.5: Run Pre-Analysis Pipeline (MANDATORY)

MANDATORY: Run static analysis, AST extraction, and call graph analysis BEFORE dispatching reviewers. This provides critical context that significantly improves review quality.

Skip Override: The skip_preanalysis parameter allows bypassing this step ONLY when explicitly requested by the user. This is NOT recommended.

Step 2.5.1: Install and Run Mithril

# ⚠️ SYNC NOTE: This Mithril install logic is also in default/commands/codereview.md (Step 0).
# If you change the install pattern or CLI flags, update both locations.
# Check if mithril is available
if ! command -v mithril &> /dev/null; then
    echo "mithril not found. Installing..."
    if command -v go &> /dev/null; then
        go install github.com/lerianstudio/mithril@latest
        GOPATH_DIR="$(go env GOPATH)"
        [[ -n "$GOPATH_DIR" ]] && export PATH="$PATH:$GOPATH_DIR/bin"
    else
        echo "Go is required to install mithril. Install Go from https://go.dev/dl/"
        echo "DEGRADED MODE: Proceeding without pre-analysis"
    fi
fi

# Run pre-analysis pipeline
if command -v mithril &> /dev/null; then
    if [[ -z "$BASE_SHA" || -z "$HEAD_SHA" ]]; then
        echo "WARNING: BASE_SHA or HEAD_SHA not set"
        echo "DEGRADED MODE: Proceeding without pre-analysis"
    elif mithril --base="$BASE_SHA" --head="$HEAD_SHA" --output=docs/codereview --verbose; then
        echo "Pre-analysis pipeline completed successfully"
    else
        echo "WARNING: Pre-analysis pipeline failed"
        echo "DEGRADED MODE: Proceeding without pre-analysis"
    fi
else
    echo "WARNING: mithril not available"
    echo "DEGRADED MODE: Reviewers will proceed WITHOUT static analysis context."
fi

• Timeout: Use preanalysis_timeout input (default 5 minutes)
• On success: Set preanalysis_state.success = true
• On failure: Display warning, set preanalysis_state.success = false, continue to Step 3

Step 2.5.2: Read Context Files

If pipeline succeeded, read the 6 context files:

Store each file's content in preanalysis_state.context[reviewer_name].

If a context file is missing or empty, log warning and continue (reviewer will work without context).

preanalysis_state = {
  enabled: true,
  success: false,
  context: {
    "ring:code-reviewer": null,
    "ring:security-reviewer": null,
    "ring:business-logic-reviewer": null,
    "ring:test-reviewer": null,
    "ring:nil-safety-reviewer": null,
    "ring:consequences-reviewer": null
  }
}

Step 3: Dispatch All 6 Reviewers in Parallel

⛔ CRITICAL: All 6 reviewers MUST be dispatched in a SINGLE message with 6 Task calls.

# Task 1: Code Reviewer
Task:
  subagent_type: "ring:code-reviewer"
  description: "Code review for [unit_id]"
  prompt: |
    ## Code Review Request
    
    **Unit ID:** [unit_id]
    **Base SHA:** [base_sha]
    **Head SHA:** [head_sha]
    
    ## What Was Implemented
    [implementation_summary]
    
    ## Requirements
    [requirements]
    
    ## Files Changed
    [implementation_files or "Use git diff"]

    ## Pre-Analysis Context

    **Static Analysis Results:**
    The following findings were automatically extracted by the pre-analysis pipeline.
    Use these to INFORM your review, not REPLACE your analysis.

    ---

    [IF preanalysis_state.context["ring:code-reviewer"] exists AND is not empty:]
    [INSERT the content of preanalysis_state.context["ring:code-reviewer"]]
    [ELSE:]
    _No pre-analysis context available. Perform standard review based on git diff._

    ---

    ## Your Focus
    - Architecture and design patterns
    - Code quality and maintainability
    - Naming conventions
    - Error handling patterns
    - Performance concerns

    ## Required Output
    ### VERDICT: PASS / FAIL

    ### Issues Found
    | Severity | Description | File:Line | Recommendation |
    |----------|-------------|-----------|----------------|
    | [CRITICAL/HIGH/MEDIUM/LOW/COSMETIC] | [issue] | [location] | [fix] |

    ### What Was Done Well
    [positive observations]

# Task 2: Business Logic Reviewer
Task:
  subagent_type: "ring:business-logic-reviewer"
  description: "Business logic review for [unit_id]"
  prompt: |
    ## Business Logic Review Request
    
    **Unit ID:** [unit_id]
    **Base SHA:** [base_sha]
    **Head SHA:** [head_sha]
    
    ## What Was Implemented
    [implementation_summary]
    
    ## Requirements
    [requirements]

    ## Pre-Analysis Context

    **Static Analysis Results:**
    The following findings were automatically extracted by the pre-analysis pipeline.
    Use these to INFORM your review, not REPLACE your analysis.

    ---

    [IF preanalysis_state.context["ring:business-logic-reviewer"] exists AND is not empty:]
    [INSERT the content of preanalysis_state.context["ring:business-logic-reviewer"]]
    [ELSE:]
    _No pre-analysis context available. Perform standard review based on git diff._

    ---

    ## Your Focus
    - Domain correctness
    - Business rules implementation
    - Edge cases handling
    - Requirements coverage
    - Data validation

    ## Required Output
    ### VERDICT: PASS / FAIL

    ### Issues Found
    | Severity | Description | File:Line | Recommendation |
    |----------|-------------|-----------|----------------|
    | [CRITICAL/HIGH/MEDIUM/LOW/COSMETIC] | [issue] | [location] | [fix] |

    ### Requirements Traceability
    | Requirement | Status | Evidence |
    |-------------|--------|----------|
    | [req] | ✅/❌ | [file:line] |

# Task 3: Security Reviewer
Task:
  subagent_type: "ring:security-reviewer"
  description: "Security review for [unit_id]"
  prompt: |
    ## Security Review Request

    **Unit ID:** [unit_id]
    **Base SHA:** [base_sha]
    **Head SHA:** [head_sha]

    ## What Was Implemented
    [implementation_summary]

    ## Requirements
    [requirements]

    ## Pre-Analysis Context

    **Static Analysis Results:**
    The following findings were automatically extracted by the pre-analysis pipeline.
    Use these to INFORM your review, not REPLACE your analysis.

    ---

    [IF preanalysis_state.context["ring:security-reviewer"] exists AND is not empty:]
    [INSERT the content of preanalysis_state.context["ring:security-reviewer"]]
    [ELSE:]
    _No pre-analysis context available. Perform standard review based on git diff._

    ---

    ## Your Focus
    - Authentication and authorization
    - Input validation
    - SQL injection, XSS, CSRF
    - Sensitive data handling
    - OWASP Top 10 risks

    ## Required Output
    ### VERDICT: PASS / FAIL

    ### Issues Found
    | Severity | Description | File:Line | OWASP Category | Recommendation |
    |----------|-------------|-----------|----------------|----------------|
    | [CRITICAL/HIGH/MEDIUM/LOW] | [issue] | [location] | [A01-A10] | [fix] |

    ### Security Checklist
    | Check | Status |
    |-------|--------|
    | Input validation | ✅/❌ |
    | Auth checks | ✅/❌ |
    | No hardcoded secrets | ✅/❌ |

# Task 4: Test Reviewer
Task:
  subagent_type: "ring:test-reviewer"
  description: "Test quality review for [unit_id]"
  prompt: |
    ## Test Quality Review Request

    **Unit ID:** [unit_id]
    **Base SHA:** [base_sha]
    **Head SHA:** [head_sha]

    ## What Was Implemented
    [implementation_summary]

    ## Requirements
    [requirements]

    ## Pre-Analysis Context

    **Static Analysis Results:**
    The following findings were automatically extracted by the pre-analysis pipeline.
    Use these to INFORM your review, not REPLACE your analysis.

    ---

    [IF preanalysis_state.context["ring:test-reviewer"] exists AND is not empty:]
    [INSERT the content of preanalysis_state.context["ring:test-reviewer"]]
    [ELSE:]
    _No pre-analysis context available. Perform standard review based on git diff._

    ---

    ## Your Focus
    - Test coverage for business logic
    - Edge case testing (empty, null, boundary)
    - Error path coverage
    - Test independence and isolation
    - Assertion quality (not just "no error")
    - Test anti-patterns (testing mock behavior)

    ## Required Output
    ### VERDICT: PASS / FAIL

    ### Issues Found
    | Severity | Description | File:Line | Recommendation |
    |----------|-------------|-----------|----------------|
    | [CRITICAL/HIGH/MEDIUM/LOW] | [issue] | [location] | [fix] |

    ### Test Coverage Analysis
    | Test Type | Count | Coverage |
    |-----------|-------|----------|
    | Unit | [N] | [areas] |
    | Integration | [N] | [areas] |
    | E2E | [N] | [areas] |

# Task 5: Nil-Safety Reviewer
Task:
  subagent_type: "ring:nil-safety-reviewer"
  description: "Nil/null safety review for [unit_id]"
  prompt: |
    ## Nil-Safety Review Request

    **Unit ID:** [unit_id]
    **Base SHA:** [base_sha]
    **Head SHA:** [head_sha]
    **Languages:** [Go|TypeScript|both - detect from files]

    ## What Was Implemented
    [implementation_summary]

    ## Requirements
    [requirements]

    ## Pre-Analysis Context

    **Static Analysis Results:**
    The following findings were automatically extracted by the pre-analysis pipeline.
    Use these to INFORM your review, not REPLACE your analysis.

    ---

    [IF preanalysis_state.context["ring:nil-safety-reviewer"] exists AND is not empty:]
    [INSERT the content of preanalysis_state.context["ring:nil-safety-reviewer"]]
    [ELSE:]
    _No pre-analysis context available. Perform standard review based on git diff._

    ---

    ## Your Focus
    - Nil/null pointer risks in changed code
    - Missing nil guards before dereference
    - Map access without ok check (Go)
    - Type assertions without ok check (Go)
    - Optional chaining misuse (TypeScript)
    - Error-then-use patterns

    ## Required Output
    ### VERDICT: PASS / FAIL

    ### Issues Found
    | Severity | Description | File:Line | Recommendation |
    |----------|-------------|-----------|----------------|
    | [CRITICAL/HIGH/MEDIUM/LOW] | [issue] | [location] | [fix] |

    ### Nil Risk Trace
    [For each risk: Source → Propagation → Dereference point]

# Task 6: Consequences Reviewer
Task:
  subagent_type: "ring:consequences-reviewer"
  description: "Consequences review for [unit_id]"
  prompt: |
    ## Consequences Review Request

    **Unit ID:** [unit_id]
    **Base SHA:** [base_sha]
    **Head SHA:** [head_sha]

    ## What Was Implemented
    [implementation_summary]

    ## Requirements
    [requirements]

    ## Pre-Analysis Context

    **Static Analysis Results:**
    The following findings were automatically extracted by the pre-analysis pipeline.
    Use these to INFORM your review, not REPLACE your analysis.

    ---

    [IF preanalysis_state.context["ring:consequences-reviewer"] exists AND is not empty:]
    [INSERT the content of preanalysis_state.context["ring:consequences-reviewer"]]
    [ELSE:]
    _No pre-analysis context available. Perform standard review based on git diff._

    ---

    ## Your Focus
    - Caller chain impact analysis
    - Consumer contract integrity
    - Shared state and configuration consequences
    - Type and interface propagation
    - Error handling chain consequences
    - Database/schema ripple effects

    ## Required Output
    ### VERDICT: PASS / FAIL

    ### Issues Found
    | Severity | Description | File:Line | Recommendation |
    |----------|-------------|-----------|----------------|
    | [CRITICAL/HIGH/MEDIUM/LOW] | [issue] | [location] | [fix] |

    ### Impact Trace Analysis
    [For each changed symbol: callers found, consumers found, impact status]

Step 4: Wait for All Reviewers and Parse Output

Wait for all 6 Task calls to complete.

For each reviewer:
1. Extract VERDICT (PASS/FAIL)
2. Extract Issues Found table
3. Categorize issues by severity

review_state.reviewers.code_reviewer = {
  verdict: [PASS/FAIL],
  issues: [parsed issues]
}
// ... same for other reviewers

Aggregate all issues by severity:
review_state.aggregated_issues.critical = [all critical from all reviewers]
review_state.aggregated_issues.high = [all high from all reviewers]
// ... etc

Step 5: Handle Results by Severity

Count blocking issues:
blocking_count = critical.length + high.length + medium.length

IF blocking_count == 0:
  → All reviewers PASS
  → Proceed to Step 8 (Success)

IF blocking_count > 0:
  → review_state.iterations += 1
  → IF iterations >= max_iterations: Go to Step 9 (Escalate)
  → Go to Step 6 (Dispatch Fixes)

Step 6: Dispatch Fixes to Implementation Agent

⛔ CRITICAL: You are an ORCHESTRATOR. You CANNOT edit source files directly. You MUST dispatch the implementation agent to fix ALL review issues.

Orchestrator Boundaries (HARD GATE)

See dev-team/skills/shared-patterns/standards-boundary-enforcement.md for core enforcement rules.

Key prohibition: Edit/Write/Create on source files is FORBIDDEN. Always dispatch agent.

If you catch yourself about to use Edit/Write/Create on source files → STOP. Dispatch agent.

Dispatch Implementation Agent

Task:
  subagent_type: "[implementation_agent from Gate 0]"
  description: "Fix review issues for [unit_id]"
  prompt: |
    ⛔ FIX REQUIRED - Code Review Issues Found

    ## Context
    - **Unit ID:** [unit_id]
    - **Iteration:** [iterations] of [max_iterations]

    ## Critical Issues (MUST FIX)
    [list critical issues with file:line and recommendation]

    ## High Issues (MUST FIX)
    [list high issues]

    ## Medium Issues (MUST FIX)
    [list medium issues]

    ## Requirements
    1. Fix ALL Critical, High, and Medium issues
    2. Run tests to verify fixes
    3. Commit fixes with descriptive message
    4. Return list of fixed issues with evidence

    ## For Low/Cosmetic Issues
    Add TODO/FIXME comments:
    - Low: `// TODO(review): [Issue] - [reviewer] on [date]`
    - Cosmetic: `// FIXME(nitpick): [Issue] - [reviewer] on [date]`

Anti-Rationalization for Direct Editing

See shared-patterns/orchestrator-direct-editing-anti-rationalization.md for complete anti-rationalization table.

Applies to: Step 6 (Fix dispatch after Ring reviewers) & Step 7.5.3 (Fix dispatch after CodeRabbit)

Step 7: Re-Run All Reviewers After Fixes

After fixes committed:
1. Get new HEAD_SHA
2. Go back to Step 3 (dispatch all 6 reviewers again)

⛔ CRITICAL: Always re-run ALL 6 reviewers after fixes.
Do NOT cherry-pick reviewers.

Step 7.5: CodeRabbit CLI Validation (Per-Subtask/Task)

⛔ NEW APPROACH: CodeRabbit validates EACH subtask/task as it completes, accumulating findings to a file.

CodeRabbit Integration Overview

┌─────────────────────────────────────────────────────────────────┐
│ CODERABBIT PER-UNIT VALIDATION FLOW                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ DURING REVIEW (after each subtask/task Ring reviewers pass):   │
│   1. Run CodeRabbit for that unit's files                      │
│   2. Append findings to .coderabbit-findings.md                │
│   3. Continue to next unit                                     │
│                                                                 │
│ BEFORE COMMIT (Step 8):                                        │
│   1. Display accumulated .coderabbit-findings.md               │
│   2. User decides: fix issues OR acknowledge and proceed       │
│                                                                 │
│ BENEFITS:                                                      │
│   • Catches issues close to when code was written              │
│   • Smaller scope = faster reviews (7-30 min per unit)         │
│   • Issues isolated to specific units, easier to fix           │
│   • Accumulated file provides audit trail                      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Rate Limits (Official - per developer per repository per hour)

⏱️ TIMING: Each CodeRabbit review takes 7-30+ minutes depending on scope. Run in background and check periodically for completion.

Common Commands Reference

CodeRabbit Installation Check:

which coderabbit || which cr

Used in Step 7.5.1 and after installation to verify CLI availability.

⚠️ PREREQUISITES & ENVIRONMENT REQUIREMENTS

Before attempting Step 7.5, verify your environment supports the required operations:

⛔ HARD STOP CONDITIONS - Skip Step 7.5 if ANY apply:

• Running in containerized environment without persistent storage
• CI/CD pipeline without pre-installed CodeRabbit CLI
• Non-interactive environment (no TTY for browser auth)
• Network restrictions blocking cli.coderabbit.ai
• Read-only filesystem

Environment-Specific Guidance

Local Development (RECOMMENDED)

Standard flow works: curl | sh install + browser authentication.

CI/CD Pipelines

Option A: Pre-install in CI image

# Add to your CI Dockerfile
RUN curl -fsSL https://cli.coderabbit.ai/install.sh | sh

Option B: Use API token authentication (headless)

# Set token via environment variable (add to CI secrets)
export CODERABBIT_API_TOKEN="your-api-token"
coderabbit auth login --token "$CODERABBIT_API_TOKEN"

Option C: Skip CodeRabbit in CI, run locally

# In CI config, set env var to auto-skip
export SKIP_CODERABBIT_REVIEW=true

Containerized/Docker Environments

# Option 1: Mount credentials from host
docker run -v ~/.coderabbit:/root/.coderabbit ...

# Option 2: Pass token as env var
docker run -e CODERABBIT_API_TOKEN="..." ...

# Option 3: Pre-bake into image (not recommended for tokens)

Non-Interactive/Headless Authentication

# Generate API token at: https://app.coderabbit.ai/settings/api-tokens
# Then authenticate without browser:
coderabbit auth login --token "cr_xxxxxxxxxxxxx"

Step 7.5 Flow Logic

┌─────────────────────────────────────────────────────────────────┐
│ ✅ ALL 3 RING REVIEWERS PASSED                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ Checking CodeRabbit CLI availability...                         │
│                                                                 │
│ CodeRabbit provides additional AI-powered code review that      │
│ catches race conditions, memory leaks, security vulnerabilities,│
│ and edge cases that may complement Ring reviewers.              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

⛔ HARD GATE: CodeRabbit Execution Rules (NON-NEGOTIABLE)

Why this distinction:

• If CodeRabbit IS installed → User has committed to using it → MUST run
• If CodeRabbit is NOT installed → User choice to add it → MUST ask, but can decline

FLOW:
1. Run CodeRabbit Installation Check
2. IF installed AND authenticated → Run CodeRabbit (MANDATORY, NO prompt, CANNOT skip)
3. IF installed BUT NOT authenticated → Guide authentication (REQUIRED before proceeding)
4. IF NOT installed → MUST ask user about installation (REQUIRED prompt)
5. IF user declines installation → Skip CodeRabbit, proceed to Step 8 (only valid skip path)

Anti-Rationalization for CodeRabbit Execution

Step 7.5.1: Check CodeRabbit Installation

Run the CodeRabbit Installation Check command.

IF INSTALLED AND AUTHENTICATED → MANDATORY EXECUTION (CANNOT SKIP):

┌─────────────────────────────────────────────────────────────────┐
│ ✅ CodeRabbit CLI detected - MANDATORY EXECUTION                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ CodeRabbit CLI is installed and authenticated.                  │
│                                                                 │
│ ⛔ CodeRabbit review is MANDATORY when installed.               │
│    This step CANNOT be skipped. Proceeding automatically...     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

→ Proceed directly to Step 7.5.2 (Run CodeRabbit Review) - NO user prompt, NO skip option

IF NOT INSTALLED → MUST ASK USER (REQUIRED PROMPT):

⛔ You MUST present this prompt to the user. Silent skips are FORBIDDEN.

┌─────────────────────────────────────────────────────────────────┐
│ ⚠️  CodeRabbit CLI not found - INSTALLATION PROMPT REQUIRED     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ CodeRabbit CLI is not installed on your system.                 │
│                                                                 │
│ CodeRabbit provides additional AI-powered review that catches:  │
│   • Race conditions and concurrency issues                      │
│   • Memory leaks and resource management                        │
│   • Security vulnerabilities                                    │
│   • Edge cases missed by other reviewers                        │
│                                                                 │
│ ⛔ You MUST choose one of the following options:                │
│                                                                 │
│   (a) Yes, install CodeRabbit CLI (I'll guide you)              │
│   (b) No, skip CodeRabbit and proceed to Gate 5                 │
│                                                                 │
│ ⚠️  ENVIRONMENT CHECK:                                          │
│     • Interactive terminal with browser? → Standard install     │
│     • CI/headless? → Requires API token auth                    │
│     • Container? → See Environment-Specific Guidance above      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

If user selects (a) Yes, install: → Proceed to Installation Flow below

If user selects (b) No, skip:

→ Record: "CodeRabbit review: SKIPPED (not installed, user declined installation)"
→ Proceed to Step 8 (Success Output)
→ This is the ONLY valid path to skip CodeRabbit

Step 7.5.1a: CodeRabbit Installation Flow

┌─────────────────────────────────────────────────────────────────┐
│ 📦 INSTALLING CODERABBIT CLI                                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ ⚠️  ENVIRONMENT CHECK FIRST:                                    │
│                                                                 │
│ This installation requires:                                     │
│   • curl command available                                      │
│   • Write access to $HOME or /usr/local/bin                     │
│   • Internet access to cli.coderabbit.ai                        │
│   • Non-containerized environment (or persistent storage)       │
│                                                                 │
│ If in CI/container, see "Environment-Specific Guidance" above.  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Check environment before proceeding:

# Verify prerequisites
curl --version && echo "curl: OK" || echo "curl: MISSING"
test -w "$HOME" && echo "HOME writable: OK" || echo "HOME writable: NO"
curl -sI https://cli.coderabbit.ai | head -1 | grep -q "200\|301\|302" && echo "Network: OK" || echo "Network: BLOCKED"

If prerequisites pass, install:

┌─────────────────────────────────────────────────────────────────┐
│ 📦 Step 1: Installing CodeRabbit CLI...                         │
└─────────────────────────────────────────────────────────────────┘

# Step 1: Download and install CodeRabbit CLI
curl -fsSL https://cli.coderabbit.ai/install.sh | sh

After installation, verify: Run the CodeRabbit Installation Check command.

If installation successful:

┌─────────────────────────────────────────────────────────────────┐
│ ✅ CodeRabbit CLI installed successfully!                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ Step 2: Authentication required                                 │
│                                                                 │
│ Choose your authentication method:                              │
│                                                                 │
│   (a) Browser login (interactive - opens browser)               │
│       → Best for: Local development with GUI                    │
│       → Command: coderabbit auth login                          │
│                                                                 │
│   (b) API token (headless - no browser needed)                  │
│       → Best for: CI/CD, containers, SSH sessions               │
│       → Get token: https://app.coderabbit.ai/settings/api-tokens│
│       → Command: coderabbit auth login --token "cr_xxx"         │
│                                                                 │
│   (c) Skip authentication and CodeRabbit review                 │
│                                                                 │
│ Note: Free tier allows 1 review/hour.                           │
│       Paid plans get enhanced reviews + higher limits.          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

If user selects (a) Browser login:

# Step 2a: Authenticate with CodeRabbit (opens browser)
# ⚠️ Requires: GUI environment with default browser
coderabbit auth login

If user selects (b) API token:

# Step 2b: Authenticate with API token (headless)
# Get your token from: https://app.coderabbit.ai/settings/api-tokens
coderabbit auth login --token "cr_xxxxxxxxxxxxx"

After authentication:

┌─────────────────────────────────────────────────────────────────┐
│ ✅ CodeRabbit CLI ready!                                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ Installation: Complete                                          │
│ Authentication: Complete                                        │
│                                                                 │
│ Proceeding to CodeRabbit review...                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

→ Proceed to Step 7.5.2 (Run CodeRabbit Review)

If installation failed:

┌─────────────────────────────────────────────────────────────────┐
│ ❌ CodeRabbit CLI installation failed                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ Error: [error message from curl/sh]                             │
│                                                                 │
│ Troubleshooting:                                                │
│   • Check internet connection                                   │
│   • Try manual install: https://docs.coderabbit.ai/cli/overview │
│   • macOS/Linux only (Windows not supported yet)                │
│                                                                 │
│ Would you like to:                                              │
│   (a) Retry installation                                        │
│   (b) Skip CodeRabbit and proceed to Gate 5                     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Step 7.5.2: Run CodeRabbit Review

⛔ GRANULAR VALIDATION: CodeRabbit MUST validate at the most granular level available.

DETERMINE VALIDATION SCOPE:
1. Check if current work has subtasks (from gate0_handoff or implementation context)
2. IF subtasks exist → Validate EACH SUBTASK separately
3. IF no subtasks → Validate the TASK as a whole

WHY GRANULAR VALIDATION:
- Subtask-level validation catches issues early
- Easier to pinpoint which subtask introduced problems
- Prevents "works for task A, breaks task B" scenarios
- Enables incremental fixes without re-running entire review

Step 7.5.2a: Determine Validation Scope

validation_scope = {
  mode: null,  // "subtask" or "task"
  units: [],   // list of {id, files, commits} to validate
  current_index: 0
}

IF gate0_handoff.subtasks exists AND gate0_handoff.subtasks.length > 0:
  → validation_scope.mode = "subtask"
  → FOR EACH subtask in gate0_handoff.subtasks:
      → Get files changed by this subtask (from commits or file mapping)
      → Add to validation_scope.units: {
          id: subtask.id,
          name: subtask.name,
          files: [files touched by this subtask],
          base_sha: [sha before subtask],
          head_sha: [sha after subtask]
        }
  
  Display:
  ┌─────────────────────────────────────────────────────────────────┐
  │ 📋 CODERABBIT VALIDATION MODE: SUBTASK-LEVEL                    │
  ├─────────────────────────────────────────────────────────────────┤
  │                                                                 │
  │ Detected [N] subtasks. Will validate each separately:          │
  │                                                                 │
  │   1. [subtask-1-id]: [subtask-1-name]                          │
  │      Files: [file1.go, file2.go]                               │
  │                                                                 │
  │   2. [subtask-2-id]: [subtask-2-name]                          │
  │      Files: [file3.go, file4.go]                               │
  │                                                                 │
  │   ... (up to N subtasks)                                       │
  │                                                                 │
  └─────────────────────────────────────────────────────────────────┘

ELSE:
  → validation_scope.mode = "task"
  → Add single unit: {
      id: unit_id,
      name: implementation_summary,
      files: implementation_files,
      base_sha: base_sha,
      head_sha: head_sha
    }
  
  Display:
  ┌─────────────────────────────────────────────────────────────────┐
  │ 📋 CODERABBIT VALIDATION MODE: TASK-LEVEL                       │
  ├─────────────────────────────────────────────────────────────────┤
  │                                                                 │
  │ No subtasks detected. Validating entire task:                  │
  │                                                                 │
  │   Task: [unit_id]                                              │
  │   Files: [N] files changed                                     │
  │                                                                 │
  └─────────────────────────────────────────────────────────────────┘

Step 7.5.2b: Run CodeRabbit for Each Validation Unit

coderabbit_results = {
  overall_status: "PASS",  // PASS only if ALL units pass
  units: []
}

FOR EACH unit IN validation_scope.units:
  Display:
  ┌─────────────────────────────────────────────────────────────────┐
  │ 🔍 VALIDATING: [unit.id] ([current]/[total])                    │
  ├─────────────────────────────────────────────────────────────────┤
  │ Name: [unit.name]                                              │
  │ Files: [unit.files.join(", ")]                                 │
  └─────────────────────────────────────────────────────────────────┘

# Run CodeRabbit review
# ⏱️ TIMING: 7-30+ minutes per review. Run in background if possible.

# Compare against base branch
coderabbit --prompt-only --type uncommitted --base [base_branch]

# Compare against specific commit on current branch
coderabbit --prompt-only --type uncommitted --base-commit [unit.base_sha]

# The command is synchronous - it completes when output is returned

  Parse output and record:
  unit_result = {
    id: unit.id,
    status: "PASS" | "ISSUES_FOUND",
    issues: {
      critical: [list],
      high: [list],
      medium: [list],
      low: [list]
    }
  }
  
  coderabbit_results.units.push(unit_result)
  
  IF unit_result.issues.critical.length > 0 OR unit_result.issues.high.length > 0:
    → coderabbit_results.overall_status = "ISSUES_FOUND"
  
  ─────────────────────────────────────────────────────────────────
  ⛔ MANDATORY: APPEND FINDINGS TO .coderabbit-findings.md
  ─────────────────────────────────────────────────────────────────
  
  After EACH unit validation, append results to findings file:
  
  IF .coderabbit-findings.md does NOT exist:
    → Create file with header (see "Findings File Format" below)
  
  APPEND to .coderabbit-findings.md:

Unit: [unit.id] - [unit.name]

Validated: [timestamp] Status: [PASS | ISSUES_FOUND] Files: [unit.files.join(", ")]

Issues Found

…(truncated)