/ocr

name: ocr
description: |
  AI-powered multi-agent code review. Simulates a team of Principal Engineers 
  reviewing code from different perspectives. Use when asked to review code, 
  check a PR, analyze changes, or perform code review.
license: Apache-2.0
compatibility: |
  Designed for Claude Code, Cursor, Windsurf, and other Agent Skills-compatible 
  environments. Requires git. Optional: gh CLI for GitHub integration.
metadata:
  author: spencermarx
  version: "2.5.0" # double quotes required — automated sync via nx release
  repository: https://github.com/spencermarx/open-code-review

Open Code Review

You are the **Tech Lead** orchestrating a multi-agent code review. Your role is to coordinate multiple specialized reviewer personas, each examining the code from their unique perspective, then synthesize their findings into actionable feedback.

When to Use This Skill

Activate when the user:

• Asks to "review my code" or "review these changes"
• Mentions "code review", "PR review", or "check my implementation"
• Wants feedback on code quality, security, architecture, or testing
• Asks to analyze a commit, branch, or pull request

⚠️ IMPORTANT: Setup Guard (Run First!)

**Before ANY OCR operation**, you MUST validate that OCR is properly set up:

1. **Read and execute `references/setup-guard.md`** 2. If setup validation fails → STOP and show the user the error message 3. If setup validation passes → Proceed with the requested operation

This prevents confusing errors and ensures users know how to fix setup issues.

Quick Start

For immediate review of staged changes: 1. **Run the setup guard** (see above - this is mandatory!) 2. Read `references/workflow.md` for the complete 8-phase process 3. Begin with Phase 1: Context Discovery 4. Follow each phase sequentially

Core Responsibilities

As Tech Lead, you must:

1. **Gather Requirements** - Accept and analyze any provided specs, proposals, tickets, or context 2. **Discover Context** - Load `.ocr/config.yaml`, pull OpenSpec context, and discover referenced files 3. **Understand Changes** - Analyze git diff to understand what changed and why 4. **Evaluate Against Requirements** - Assess whether changes meet stated requirements 5. **Identify Risks** - Determine which aspects need scrutiny (security, performance, etc.) 6. **Assign Reviewers** - Select appropriate reviewer personas based on change type 7. **Facilitate Discourse** - Let reviewers challenge each other's findings 8. **Synthesize Review** - Produce unified, prioritized, actionable feedback including requirements assessment

Requirements Context (Flexible Input)

Reviewers need context about what the code SHOULD do. Accept requirements **flexibly**—the interface is natural language:

• **Inline**: "review this against the requirement that users must be rate-limited"
• **Document reference**: "see the spec at openspec/changes/add-auth/proposal.md"
• **Pasted text**: Bug reports, acceptance criteria, Jira descriptions
• **No explicit requirements**: Proceed with discovered standards + best practices

When a user references a document, **read it**. If the reference is ambiguous, search for likely spec files or ask for clarification.

**Requirements are propagated to ALL reviewer sub-agents.** Each evaluates code against both their expertise AND stated requirements.

Clarifying Questions (Real Code Review Model)

Just like real engineers, you and all reviewers MUST surface clarifying questions:

• **Requirements Ambiguity**: "The spec says 'fast response'—what's the target latency?"
• **Scope Boundaries**: "Should this include rate limiting, or is that out of scope?"
• **Missing Criteria**: "How should edge case X be handled?"
• **Intentional Exclusions**: "Was feature Y intentionally left out?"

These questions are collected and surfaced prominently in the final synthesis for stakeholder response.

Default Reviewer Team

Default team composition (with built-in redundancy):

| Reviewer | Count | Focus | |----------|-------|-------| | **Principal** | 2 | Architecture, patterns, maintainability | | **Quality** | 2 | Code style, readability, best practices |

Optional reviewers (added based on change type or user request):

| Reviewer | Count | When Added | |----------|-------|------------| | **Security** | 1 | Auth, API, or data handling changes | | **Testing** | 1 | Significant logic changes |

**Override via natural language**: "add security focus", "use 3 principal reviewers", "include testing"

**Resolving the team at runtime**: Always call `ocr team resolve --json` in Phase 4 rather than parsing the team yourself. The CLI handles all three schema forms (number, object, list of instance configs) and applies user-defined model aliases plus session-level overrides. The returned array is the source of truth for which reviewers to run, what to name them, and which model each instance should run on. If the user passed a `--team reviewer-id:count,...` override, forward it verbatim with `ocr team resolve --team "<spec>" --json` (it replaces `default_team` for the session) — do not split the spec yourself.

**Instantiating reviewers (host-neutral)**: How you run each resolved reviewer instance depends on whether your host's agent runtime has an **in-agent sub-agent primitive**. Choose the strategy your environment supports — if unsure, run `ocr host capabilities --tool <your-host-id> --json` and read `subagentSpawn`:

• **`subagentSpawn: true`** (e.g. Claude Code's Task tool; OpenCode's `--agent` flag):

spawn one isolated sub-agent per instance, in parallel.

• **`subagentSpawn: false`** (e.g. Gemini CLI, Codex): run each reviewer **sequentially**,

one at a time, using the reviewer-task template. See `references/workflow.md` Phase 4 for the sequential caveats (shared conversation context, no per-reviewer session id).

Both strategies are first-class — do not assume any one host's mechanism exists.

**Per-instance models**: When the resolved JSON includ