From a7c2bbceaf96547a4bc6dc7de5f60d620e7d8b9c Mon Sep 17 00:00:00 2001 From: Nizar Alrifai Date: Fri, 25 Sep 2026 11:33:13 -0700 Subject: [PATCH 1/3] docs(code-review): steer model selection to review_depth presets Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- docs/enterprise/security-review.mdx | 3 +- docs/guides/droid-exec/code-review.mdx | 44 +++++++++++++++++--------- 2 files changed, 31 insertions(+), 16 deletions(-) diff --git a/docs/enterprise/security-review.mdx b/docs/enterprise/security-review.mdx index 00346538..9de0ba60 100644 --- a/docs/enterprise/security-review.mdx +++ b/docs/enterprise/security-review.mdx @@ -98,10 +98,11 @@ 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_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`. | +PR security reviews use the same [`review_depth`](/guides/droid-exec/code-review#review-depth) preset as code review, so you don't need to choose a model. + ## Methodology Security review uses the built-in `security-review` skill. In PR automation, Droid Action runs a dedicated `security-reviewer` subagent that loads this methodology before reading files, then traces changed data flows across authentication, authorization, validation, database, network, filesystem, and LLM boundaries. diff --git a/docs/guides/droid-exec/code-review.mdx b/docs/guides/droid-exec/code-review.mdx index de0b71e3..fd900b57 100644 --- a/docs/guides/droid-exec/code-review.mdx +++ b/docs/guides/droid-exec/code-review.mdx @@ -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. @@ -99,7 +99,33 @@ 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. + + + 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. + + + + Only needed if your organization requires a specific model provider. The `review_model`, `security_model`, `fill_model`, and `reasoning_effort` inputs take priority over the depth preset. + + 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: 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 @@ -153,16 +179,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: @@ -191,9 +207,7 @@ 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). | | `include_suggestions` | `true` | Include code suggestion blocks in comments | Security review inputs are documented in [Security Review](/enterprise/security-review#configuration). From 00b8c5f2aa2f09096e91d6e012ac850f8e7e8498 Mon Sep 17 00:00:00 2001 From: Nizar Alrifai Date: Fri, 25 Sep 2026 11:36:20 -0700 Subject: [PATCH 2/3] docs(code-review): label model overrides as advanced instead of hiding them Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- docs/enterprise/security-review.mdx | 3 +- docs/guides/droid-exec/code-review.mdx | 38 +++++++++++++++----------- 2 files changed, 23 insertions(+), 18 deletions(-) diff --git a/docs/enterprise/security-review.mdx b/docs/enterprise/security-review.mdx index 9de0ba60..26fb09cd 100644 --- a/docs/enterprise/security-review.mdx +++ b/docs/enterprise/security-review.mdx @@ -98,11 +98,10 @@ 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` | `""` | 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`. | -PR security reviews use the same [`review_depth`](/guides/droid-exec/code-review#review-depth) preset as code review, so you don't need to choose a model. - ## Methodology Security review uses the built-in `security-review` skill. In PR automation, Droid Action runs a dedicated `security-reviewer` subagent that loads this methodology before reading files, then traces changed data flows across authentication, authorization, validation, database, network, filesystem, and LLM boundaries. diff --git a/docs/guides/droid-exec/code-review.mdx b/docs/guides/droid-exec/code-review.mdx index fd900b57..5a57cf05 100644 --- a/docs/guides/droid-exec/code-review.mdx +++ b/docs/guides/droid-exec/code-review.mdx @@ -105,27 +105,31 @@ Each preset picks the model and reasoning effort for you, and Factory keeps it o 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. - - Only needed if your organization requires a specific model provider. The `review_model`, `security_model`, `fill_model`, and `reasoning_effort` inputs take priority over the depth preset. +### Advanced: model overrides - 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. + + Most teams should use `review_depth` and skip this section. Overrides are only needed if your organization requires a specific model provider. + - | 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` | +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. - ```yaml - with: - automatic_review: true - review_model: anthropic-latest-balanced - ``` +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: 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. +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. - +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 @@ -208,6 +212,8 @@ Guidelines: |-------|---------|-------------| | `automatic_review` | `false` | Automatically review PRs without `@droid review` | | `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). From e9a324a1a901d2307f73745a8ca265f01fc83196 Mon Sep 17 00:00:00 2001 From: Nizar Alrifai Date: Fri, 25 Sep 2026 11:39:53 -0700 Subject: [PATCH 3/3] docs(code-review): explain that deep is Factory's hand-picked review model Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- docs/guides/droid-exec/code-review.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/guides/droid-exec/code-review.mdx b/docs/guides/droid-exec/code-review.mdx index 5a57cf05..9cf74afa 100644 --- a/docs/guides/droid-exec/code-review.mdx +++ b/docs/guides/droid-exec/code-review.mdx @@ -101,6 +101,8 @@ with: 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. + 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. @@ -124,7 +126,7 @@ If you set a model, use a provider tier alias. Factory keeps each alias on its r ```yaml with: automatic_review: true - review_model: anthropic-latest-balanced + 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.