Core Concepts
These concepts will help you get the most out of Otto Detective.
Organizations
An Organization is your team's workspace in Otto. It contains:
- Team members with different roles (Owner, Admin, Member)
- Integrations: GitHub, Azure DevOps, and the Linear and Jira integrations used by Otto Builder
- Review settings and projects
- Billing and usage tracking
Member Roles
| Role | Permissions |
|---|---|
| Owner | Full access, billing, delete org |
| Admin | Manage rules, integrations, settings |
| Member | View-only access |
Reviews
A review is what Otto posts on a pull request: a verdict (Approved, Changes requested, or Commented; posted as a native review on GitHub and stated in the summary thread on Azure DevOps), inline findings on the lines that changed, and a summary that ends with a merge-confidence score. Otto never commits, pushes, or merges.
Severity
Every finding is ranked P0–P3, from critical (data loss, a security breach, an outage, or a broken build) to non-blocking suggestions. See Introduction for the full scale.
Merge confidence
Every review ends with Merge confidence: X/5 and a one-sentence reason:
| Score | Meaning |
|---|---|
| 5 | Safe to merge: no P0, P1, or P2 findings remain |
| 4 | Safe to merge: only minor P2 concerns, nothing P0 or P1 |
| 3 | Medium risk: P2 issues worth fixing, though none block on their own |
| 2 | Not safe to merge: at least one P1, or several serious P2s |
| 1 | Blocker: a P0 or a high-confidence risk like data loss or a deploy break |
Review settings
Organization-wide review settings apply to every repository you connect:
- Review depth: Light (quick reviews for small, low-risk changes), Standard (focused reviews for everyday changes), Deep (thorough reviews that trace changes across the codebase; the default), or Max (the most thorough review, for critical code paths). Otto picks the model behind each depth. Switch anytime; it applies to the next review.
- Review instructions: tell Otto what matters to your team, such as areas to focus on, conventions to enforce, or things to skip. Instructions shape what Otto looks for; they don't change its severity scale or how it scores merge confidence.
- Automatic reviews: on by default for the repositories you connect. Turn them off org-wide whenever you need to.
- Comment style (GitHub): keep one updated summary per pull request, or post a new one with each review.
To configure a single repository, commit an otto.yml file. It can set depth and instructions per path, ignore files, and skip automatic reviews.
Credits
Reviews are charged per pull request from prepaid credits. The charge depends on the review depth and the size of the change, and you can see what each PR cost in your dashboard. There are no per-seat fees. See Billing for details.
Otto Builder
Otto also includes Otto Builder, a separate set of ticket-driven workflows that work from Linear or Jira. Builder uses its own concepts:
- Lifecycle: preset agents that clarify a ticket, plan the work, and implement it. Configure the phases in Settings → Lifecycle.
- Rules: an opt-in filter that decides which tickets Builder picks up. With no rules, no tickets are picked up.
- Projects: group repositories. Builder uses them to link a ticket project to the repositories it works in.
- Agents: custom agents with their own prompts and configuration for one-off workflows.
The pages under Use cases and Workflows, the Linear and Jira integration pages, and Verification (verify.yml) describe Otto Builder. The rest of these docs describe Otto Detective, the reviewer.