# Local Code Review

Use the /review command to analyze local code changes with AI-powered review workflows

## Overview

The `/review` command provides a local workflow for analyzing code changes with AI-powered insights. It offers multiple review modes to fit different development scenarios, from reviewing uncommitted changes to analyzing full branches or specific commits.

When you run `/review`, droid guides you through selecting a review type, configuring parameters, and then performs a comprehensive analysis of your code changes based on industry-standard review guidelines.

## Quick start

<Steps>
  <Step title="Start the review flow">
    In a local droid session, type:
    ```bash
    /review
    ```
  </Step>

  <Step title="Select a review type">
    Choose from four review presets:
    - **Review against a base branch** - PR-style review comparing your branch to a base branch
    - **Review uncommitted changes** - Analyze working directory changes (staged, unstaged, and untracked)
    - **Review a commit** - Examine a specific commit from history
    - **Custom review instructions** - Define your own review criteria
  </Step>

  <Step title="Configure parameters">
    Depending on your selection:
    - For **base branch reviews**: Select the target branch (e.g., `main`, `develop`)
    - For **commit reviews**: Choose a commit from the interactive list
    - For **custom reviews**: Enter your review instructions
  </Step>

  <Step title="Review the findings">
    Droid analyzes the code changes and provides:
    - Prioritized findings with severity levels [P0-P3]
    - Specific file locations and line numbers
    - Suggested fixes with code suggestions
    - Overall assessment of the changes
  </Step>
</Steps>

## Review types

### Review against a base branch

Compare your current branch against a base branch (like a pull request review). This is ideal for pre-PR reviews or checking what changes would be merged.

**How it works:**

1. Select "Review against a base branch"
2. Choose your target base branch from the list (local and remote branches shown)
3. Droid finds the merge base and reviews the diff

**Use cases:**

- Pre-commit PR reviews
- Checking branch changes before creating a pull request
- Validating feature branch against main/develop

**Example workflow:**

```text
> /review
# Select: Review against a base branch
# Choose: origin/main
# Droid reviews all changes that would be merged
```

### Review uncommitted changes

Analyze all current working directory changes: staged files, unstaged modifications, and untracked files.

**Use cases:**

- Quick sanity check before committing
- Reviewing work in progress
- Finding issues early in development

**Example workflow:**

```text
> /review
# Select: Review uncommitted changes
# Droid immediately reviews all working directory changes
```

### Review a commit

Examine the changes introduced by a specific commit in your repository history.

**How it works:**

1. Select "Review a commit"
2. Browse commits with hash, message, author, and date
3. Select a commit to review

**Use cases:**

- Reviewing recent commits for issues
- Understanding changes in a specific commit
- Post-merge review of teammate's work

**Example workflow:**

```text
> /review
# Select: Review a commit
# Browse and select: abc1234 - "Add user authentication"
# Droid reviews that specific commit's changes
```

### Custom review instructions

Define your own review criteria for specialized analysis.

**Use cases:**

- Performance analysis
- Checking specific coding standards
- Domain-specific validations

**Example workflow:**

```text
> /review
# Select: Custom review instructions
# Enter: "Focus on performance regressions and unnecessary re-renders"
# Droid performs a targeted review
```

## Review guidelines

All code reviews follow a structured rubric designed to produce actionable, high-quality feedback.

### Severity levels

| Priority | Meaning | Typical response |
| :------- | :------ | :--------------- |
| `[P0]` | Critical issue blocking release or operations. | Fix immediately before merge or deploy. |
| `[P1]` | Urgent issue that should be addressed in the next cycle. | Fix before the work is considered complete. |
| `[P2]` | Normal priority issue to fix eventually. | Track or fix when practical. |
| `[P3]` | Low-priority nice-to-have improvement. | Consider if it aligns with nearby work. |

### Bug detection criteria

The AI flags an issue as a bug only when all of these are true:

| Criterion | Meaning |
| :-------- | :------ |
| Meaningful impact | Affects accuracy, performance, security, or maintainability. |
| Discrete and actionable | Clear, specific issue with a clear fix. |
| Appropriate rigor | Does not demand more rigor than the rest of the codebase. |
| Introduced in changes | Added by the reviewed changes, not pre-existing. |
| Worth fixing | The author would likely fix it if made aware. |
| No unstated assumptions | Based on verifiable facts, not speculation. |
| Provably affected | Identifies specific affected code, not a theoretical risk. |
| Not intentional | Clearly not a deliberate design choice. |

### Comment and output standards

| Area | Standard |
| :--- | :------- |
| Reasoning | Explain why the issue matters and which conditions trigger it. |
| Severity | Use `[P0]` through `[P3]` to communicate impact accurately. |
| Brevity | Keep each finding to one paragraph. |
| Code snippets | Limit Markdown code chunks to three lines. |
| Tone | Stay matter-of-fact and avoid accusatory language or excessive flattery. |
| Finding title | Use a clear title, 80 characters or fewer, in imperative mood. |
| Location | Include file paths and line numbers when applicable. |
| Suggested fix | Include a concrete replacement only when it is safe and specific. |
| Overall assessment | State whether the changes are correct or incorrect, plus a one to three sentence summary. |

## Tips and best practices

### Making the most of reviews

- Run reviews frequently during development, not just before commits
- Use custom instructions for domain-specific concerns your team cares about
- Treat P0/P1 findings seriously, they represent real issues worth addressing
- Review the overall assessment for context on whether changes are sound

### Navigating the review UI

- Press <Kbd>Esc</Kbd> to go back at any step in the review flow
- From the preset selection, <Kbd>Esc</Kbd> closes the review overlay
- Use arrow keys to navigate branch/commit lists
- Type to filter branches by name in real-time

## Automated reviews in CI

The `/review` command is meant for local CLI sessions. For automated PR reviews in CI/CD, use the [Automated Code Review](/software-factory/code-review-ci) workflow, which supports:

{/* sweep-allow: term-bullets */}

- **Automatic PR reviews** triggered by pull request events or comments
- **Review depth** (`deep` or `shallow`) to control thoroughness and cost
- **Custom review guidelines** for repository-specific checks

Set it up by running `droid` and entering `/install-code-review`, or run a one-off review with:

```bash
droid exec "Review the changes in this PR for correctness and performance regressions"
```

See the [Automated Code Review guide](/software-factory/code-review-ci) for full configuration options.

<RelatedLinks>
  <RelatedLink href='/droid-cli/cli-reference' title='CLI Reference'>
    Complete command reference including `/review`.
  </RelatedLink>
  <RelatedLink href='/software-factory/code-review-ci' title='Automated Code Review'>
    Wire Droid review into GitHub Actions for every pull request.
  </RelatedLink>
</RelatedLinks>