> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# PR reviews

> Capy's Review agent reads pull request diffs, analyzes changes, and posts structured findings as inline GitHub comments — categorized by type and severity.

## Overview

Capy analyzes pull request diffs in two complementary ways: a **PR summary** and **review findings**. The summary explains what changed at a functional level, grouped by capability rather than by file. Findings identify specific issues, categorize them, assign severity, and attach them to code locations.

You can trigger reviews from Captain or directly from the PR page. When Captain is managing the task, it handles the full triage-and-fix loop after the review completes.

## Triggering a review

You can start a review in three ways:

1. **From Captain**

   After Captain creates a PR for a completed task, it automatically triggers a review when permissions allow. Captain passes context about what the task was meant to accomplish, so the Review agent evaluates the diff against intended behavior, not just raw code changes.

   You can also ask Captain to review any PR at any time, for example `review PR #42` or `run the review agent on SCO-005`.

2. **From the PR page**

   Open any pull request in the Capy dashboard and click **Review** to run a manual review.

3. **Automatic on PR events**

   Enable **Auto-review PRs** in your project settings to automatically review every PR when it's opened or updated. This applies to PRs not managed by Captain - draft PRs are skipped, and PRs associated with Capy tasks are skipped because Captain handles those reviews separately. No user-level permission is needed; the setting is project-wide.

## Review permissions

By default, Capy asks for permission before running a review. When Captain wants to review a PR, you get a permission card with four options:

* **Deny** - skip the review
* **Allow this time** - one-time approval (expires after about 5 minutes)
* **Allow for this run** - approve for the current Captain session
* **Always allow** - enable auto-review permanently

**Always allow** is the same setting as the **PR reviews** toggle in **Settings → Preferences**. When you enable it, Capy reviews PRs automatically without prompting, and any PR where you are the author gets reviewed.

You only need to grant permanent permission once. After auto-review is enabled, future reviews run without interruption.

## What a review produces

PR summaries and reviews are separate processes run by different agents.

**PR summary**

A separate Summary agent reads the full diff and groups changes by functional capability, not by file. This gives you a fast, high-level view of what the PR accomplishes. The summary updates automatically whenever the PR changes (for example, when new commits are pushed), and it runs independently of reviews.

**Findings**

When you run a review, the Review agent analyzes the diff for issues and emits structured findings. Each finding includes a title and rationale, category, severity, and code location (file path plus line number).

## Finding categories

| Category            | What it covers                                           |
| ------------------- | -------------------------------------------------------- |
| **Bug**             | Logic errors, incorrect behavior, crashes                |
| **Risk**            | Security issues, race conditions, data loss potential    |
| **Maintainability** | Code clarity, naming, documentation gaps                 |
| **Refactor**        | Structural improvements, duplication, pattern violations |

## Severity levels

| Severity     | Meaning                                                   |
| ------------ | --------------------------------------------------------- |
| **Critical** | Must fix before merging - security holes, data corruption |
| **High**     | Likely to cause problems in production                    |
| **Medium**   | Should address - maintainability or correctness concerns  |
| **Low**      | Style, minor improvements, nice-to-haves                  |

## GitHub comments

Findings with **medium severity or higher** are posted as inline review comments on GitHub, attached to the relevant lines in the PR.

Low severity findings stay in Capy's dashboard only, so GitHub threads stay focused on higher-impact issues.

Re-reviews do not flag the same issue twice. If a finding was already reported, Capy skips it.

When a finding is marked **resolved** or **irrelevant**, Capy automatically resolves the corresponding GitHub review thread.

## Triage and resolution

Each finding has a triage status.

| Status         | Meaning                           |
| -------------- | --------------------------------- |
| **Open**       | Active issue that needs attention |
| **Resolved**   | The issue has been fixed          |
| **Irrelevant** | False positive or not applicable  |

When Captain is managing the task, it triages automatically after review, marking false positives as **irrelevant**, confirming already-fixed issues as **resolved**, and sending real issues to the Build agent for fixing.

You can override any triage decision. If Captain marks a finding as irrelevant but you disagree, you can reopen it.

You can also triage findings manually from the Capy dashboard without Captain.

## Re-reviews

Re-reviews are incremental. Previously **irrelevant** findings are skipped. **Resolved** findings are re-checked and only re-flagged if the issue persists. **Open** findings are re-flagged only when the referenced code changed, and new issues in new or modified code are flagged normally.

## Custom review instructions

Create a `.capy/REVIEW.md` file in your repository to customize how reviews work. This is the Review agent's equivalent of `BUILD.md` - it only reads this file.

```markdown theme={null}
# Review Instructions

## Do not flag

- Snapshot ID changes are normal workflow
- Intentional fallback patterns are backward compat
- Defensive defaults are project convention

## Severity

- Only flag medium+ for user-facing bugs
- Style/preference issues should be low priority

## Focus areas

- Always check for SQL injection in new queries
- Flag any direct database access outside the repository layer
```

Changes to `REVIEW.md` take effect on the next review. If `.capy/REVIEW.md` is not found, the Review agent falls back to `AGENTS.md` (or `CLAUDE.md`) at the repository root.