ocr

Category: Tools & Productivity | Uploader: spencermarx | Downloads: 0 | Version: v1.0（Latest）

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.

Changelog: Source: GitHub https://github.com/spencermarx/orc

Directory Structure

Current level: .ocr/skills/

📁 assets/
- 📄 ocr-gitignore 113 B
- 📄 reviewer-template.md 2.1 KB
📁 references/
- 📁 map-personas/
  - 📄 architect.md 3.3 KB
  - 📄 flow-analyst.md 3.2 KB
  - 📄 requirements-mapper.md 3.8 KB
- 📁 reviewers/
  - 📄 accessibility.md 3.1 KB
  - 📄 ai.md 3.2 KB
  - 📄 anders-hejlsberg.md 4.1 KB
  - 📄 architect.md 3.1 KB
  - 📄 backend.md 2.8 KB
  - 📄 data.md 3.2 KB
  - 📄 devops.md 3.2 KB
  - 📄 docs-writer.md 4.3 KB
  - 📄 dx.md 3.0 KB
  - 📄 frontend.md 2.9 KB
  - 📄 fullstack.md 3.1 KB
  - 📄 infrastructure.md 3.0 KB
  - 📄 john-ousterhout.md 3.8 KB
  - 📄 kamil-mysliwiec.md 4.3 KB
  - 📄 kent-beck.md 3.7 KB
  - 📄 kent-dodds.md 4.5 KB
  - 📄 martin-fowler.md 3.9 KB
  - 📄 mobile.md 3.3 KB
  - 📄 performance.md 3.1 KB
  - 📄 principal.md 2.2 KB
  - 📄 quality.md 2.4 KB
  - 📄 reliability.md 3.2 KB
  - 📄 rich-hickey.md 4.6 KB
  - 📄 sandi-metz.md 4.4 KB
  - 📄 security.md 2.5 KB
  - 📄 staff-engineer.md 3.2 KB
  - 📄 tanner-linsley.md 4.3 KB
  - 📄 testing.md 2.3 KB
  - 📄 vladimir-khorikov.md 4.2 KB
- 📄 context-discovery.md 5.2 KB
- 📄 discourse.md 4.6 KB
- 📄 final-template.md 12.5 KB
- 📄 map-agent-task.md 5.9 KB
- 📄 map-template.md 6.9 KB
- 📄 map-workflow.md 21.3 KB
- 📄 reviewer-task.md 6.7 KB
- 📄 session-files.md 9.9 KB
- 📄 session-state.md 10.2 KB
- 📄 setup-guard.md 4.6 KB
- 📄 workflow.md 28.3 KB
📄 AGENTS.md 2.0 KB
📄 SKILL.md 7.6 KB

SKILL.md

---
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: "1.0.0"
  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"

## Reviewer Agency

Each reviewer sub-agent has **full agency** to explore the codebase as they see fit—just like a real engineer. They:

- Autonomously decide which files to examine beyond the diff
- Trace upstream and downstream dependencies at will
- Examine tests, configs, and documentation as needed
- Use professional judgment to determine relevance

Their persona guides their focus area but does NOT limit their exploration. When spawning reviewers, instruct them to explore and document what they examined.

## Configuration

Review `.ocr/config.yaml` for:
- `context`: Direct project context injected into all reviews
- `context_discovery`: OpenSpec integration and reference files to discover
- `rules`: Per-severity review rules (critical, important, consider)
- `default_team`: Reviewer team composition

## Workflow Summary

```
Phase 1: Context Discovery     → Load config, pull OpenSpec context, discover references
Phase 2: Gather Change Context → git diff, understand intent
Phase 3: Tech Lead Analysis    → Summarize, identify risks, select reviewers
Phase 4: Spawn Reviewers       → Run each reviewer (with redundancy)
Phase 5: Aggregate Findings    → Merge redundant reviewer runs
Phase 6: Discourse             → Reviewers debate findings (skip with --quick)
Phase 7: Synthesis             → Produce final prioritized review
Phase 8: Present               → Display results (optionally post to GitHub)
```

For complete workflow details, see `references/workflow.md`.

## Session Storage

> **See `references/session-files.md` for the authoritative file manifest.**

All review artifacts are stored in `.ocr/sessions/{YYYY-MM-DD}-{branch}/`:

| File | Description |
|------|-------------|
| `discovered-standards.md` | Merged project context (shared) |
| `requirements.md` | User-provided requirements (shared, if any) |
| `context.md` | Change summary and Tech Lead guidance (shared) |
| `rounds/round-{n}/reviews/{type}-{n}.md` | Individual reviewer outputs (per-round) |
| `rounds/round-{n}/discourse.md` | Cross-reviewer discussion (per-round) |
| `rounds/round-{n}/final.md` | Synthesized final review (per-round) |

## Commands

Available slash commands (format varies by tool):

| Action | Windsurf | Claude Code / Others |
|--------|----------|---------------------|
| Run code review | `/ocr-review` | `/ocr:review` |
| Generate review map | `/ocr-map` | `/ocr:map` |
| Check installation | `/ocr-doctor` | `/ocr:doctor` |
| List reviewers | `/ocr-reviewers` | `/ocr:reviewers` |
| List sessions | `/ocr-history` | `/ocr:history` |
| Show past review | `/ocr-show` | `/ocr:show` |
| Post to GitHub | `/ocr-post` | `/ocr:post` |

**Why two formats?**
- **Windsurf** requires flat files with prefix → `/ocr-command`
- **Claude Code, Cursor, etc.** support subdirectories → `/ocr:command`

Both invoke the same underlying functionality.

### Map Command

The `/ocr:map` command generates a **Code Review Map** for large, complex changesets:
- Section-based grouping with checkboxes for tracking
- Flow context (upstream/downstream dependencies)
- Requirements coverage (if requirements provided)

**When to use**: Extremely large changesets (multi-hour human review). For most cases, `/ocr:review` is sufficient.

See `references/map-workflow.md` for complete workflow.

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

ocr

Directory Structure

SKILL.md

Report

Notice