Skip to content

docs(code-review): steer model selection to review_depth presets #41

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
factory-nizar wants to merge 3 commits into from
+38 −16
Closed

docs(code-review): steer model selection to review_depth presets #41

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a7c2bbc
docs(code-review): steer model selection to review_depth presets
factory-nizar Sep 25, 2026
00b8c5f
docs(code-review): label model overrides as advanced instead of hidin…
factory-nizar Sep 25, 2026
e9a324a
docs(code-review): explain that deep is Factory's hand-picked review …
factory-nizar Sep 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/enterprise/security-review.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ These are the Droid Action security inputs currently wired for the workflows doc
| Input | Default | Description |
| --- | --- | --- |
| `automatic_security_review` | `false` | Run security review automatically on PRs without requiring `@droid security`. |
| `security_model` | `""` | Override the model used for security review candidate generation and full-repository scans. Falls back to `review_model` if unset. |
| `security_model` | `""` | Advanced. Override the model used for security review candidate generation and full-repository scans. Falls back to `review_model` if unset. When empty, PR security reviews follow the same [`review_depth`](/guides/droid-exec/code-review#review-depth) preset as code review. See [Advanced: model overrides](/guides/droid-exec/code-review#advanced-model-overrides). |
| `security_severity_threshold` | `medium` | Full-repository scans only: minimum severity to include in the generated report. |
| `security_notify_team` | `""` | Full-repository scans only: GitHub team to cc in the generated scan PR body, such as `@org/security-team`. |

Expand Down
52 changes: 37 additions & 15 deletions docs/guides/droid-exec/code-review.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ For the security architecture behind the GitHub App, see [GitHub Integration Sec

## Review depth

The `review_depth` input controls the thoroughness and cost of each review. You choose the depth during `/install-code-review` setup, or set it directly in your workflow.
The `review_depth` input is the only setting you need to choose how reviews run. You pick the depth during `/install-code-review` setup, or set it directly in your workflow.

- **`deep`** (default) — Thorough analysis with higher reasoning effort. Catches more subtle bugs but costs more per review. Best for production code and security-sensitive repos.
- **`shallow`** — Faster, more cost-effective reviews that cover surface-level issues. Good for high-volume repos, draft PRs, or teams watching spend.
Expand All @@ -99,7 +99,39 @@ with:
review_depth: deep # or shallow
```

You can also override the model or reasoning effort directly with `review_model` and `reasoning_effort`, which take precedence over the depth preset.
Each preset picks the model and reasoning effort for you, and Factory keeps it on its recommended model as new models ship. Your reviews get upgrades without editing the workflow or updating `droid-action`. We recommend using a preset rather than choosing a model yourself.

`deep` is what the Factory team uses on its own repositories. When you pick `deep`, you get the model Factory has hand-picked for code review: a strong, balanced model run with high reasoning effort, updated as better models ship.

<Note>
If your workflow sets `review_model`, `security_model`, or `reasoning_effort` from an earlier setup, remove them so reviews follow the preset and stay current.
</Note>

### Advanced: model overrides

<Warning>
Most teams should use `review_depth` and skip this section. Overrides are only needed if your organization requires a specific model provider.
</Warning>

The `review_model`, `security_model`, `fill_model`, and `reasoning_effort` inputs take priority over the depth preset. `security_model` falls back to `review_model` when unset.

If you set a model, use a provider tier alias. Factory keeps each alias on its recommended model for that provider and tier, so your reviews still pick up new models automatically. An alias stays in the same price tier when its model changes.

| Provider | Aliases |
| --- | --- |
| OpenAI | `openai-latest-premium`, `openai-latest-balanced`, `openai-latest-fast` |
| Anthropic | `anthropic-latest-premium`, `anthropic-latest-balanced`, `anthropic-latest-fast` |
| Open-weight models | `oss-latest-premium`, `oss-latest-balanced`, `oss-latest-fast` |

```yaml
with:
automatic_review: true
review_model: openai-latest-premium # or anthropic-latest-balanced
```

Your organization's model policy is checked against the model an alias currently resolves to. If that model is not allowed, Droid falls back to your organization's default model and says so in the tracking comment.

Exact model IDs are also accepted, but they never upgrade on their own, so reviews stay on that model until you edit the workflow. We do not recommend them.

## Security review

Expand Down Expand Up @@ -153,16 +185,6 @@ Additional checks for this codebase:

These guidelines are automatically picked up and injected into every review run. No workflow changes needed.

### Change the model

Use a different model for reviews:

```yaml
droid exec --auto high --model claude-sonnet-4-5-20250929 -f prompt.txt
# Or use a faster model for quicker feedback:
droid exec --auto high --model claude-haiku-4-5-20251001 -f prompt.txt
```

### Skip certain PRs

Add conditions to skip reviews for specific cases:
Expand Down Expand Up @@ -191,9 +213,9 @@ Guidelines:
| Input | Default | Description |
|-------|---------|-------------|
| `automatic_review` | `false` | Automatically review PRs without `@droid review` |
| `review_depth` | `deep` | Review preset: `deep` (thorough) or `shallow` (fast) |
| `review_model` | (from depth) | Override model for code review |
| `reasoning_effort` | (from depth) | Override reasoning effort |
| `review_depth` | `deep` | Review preset: `deep` (thorough) or `shallow` (fast). See [Review depth](#review-depth). |
| `review_model` | (from depth) | Advanced. Override the code review model. See [Advanced: model overrides](#advanced-model-overrides). |
| `reasoning_effort` | (from depth) | Advanced. Override reasoning effort. See [Advanced: model overrides](#advanced-model-overrides). |
| `include_suggestions` | `true` | Include code suggestion blocks in comments |

Security review inputs are documented in [Security Review](/enterprise/security-review#configuration).
Expand Down