## Problem We are introducing a second, deeper Duo Code Review alongside the existing one. Mockups now exist exploring how a user might request it on a merge request and how an administrator might configure the default. They were built to explain the idea rather than to be consistent with each other, and the labels in them are placeholders. The vocabulary is load-bearing. The same words appear in the quick action, the reviewer badge, the settings label and its helper text, the API, and the documentation. It is the cheapest thing to settle first and the most expensive thing to change later. So this issue settles the naming, then uses it to finalize the design across every surface. There is one further question that only becomes visible once levels exist: **foundational flows are enabled individually today**, so shipping levels as separate flows would force administrators to enable each one. Users should think about "Code Review Flow" as one thing with a depth setting, rather than as a set of flows to switch on. ## Scope This issue decides: 1. What we call the control and its levels, customer-facing and internal 2. How a user requests and sees a level on a merge request 3. How an administrator configures the default 4. How model selection is structured now that available models vary by level 5. How levels present in flow enablement, given they are built as separate flows ## Guiding principle **Depth changes what Duo looks at, not how it behaves.** A Deep review and a Standard review should be indistinguishable in their output: the same comment format, tone, placement, summary structure and interaction affordances. What changes is the context gathered and the work done behind the scenes to produce it. In practice that means: - Individual inline comments read the same at any depth: same format, same tone, no per-comment styling marking which depth produced them - No comment types, surfaces or interactions that exist at one level and not the other - Nobody has to learn a second review format, and nothing downstream has to parse two shapes **Open question: where do we surface which depth ran?** There is a real argument that users want to know, since it affects how much weight to give the review. The reviewer assignment is one home and the mockups already put it there. The summary comment is another plausible one, and arguably the better fit, because depth is a property of the review as a whole rather than of any individual finding. Marking every inline comment is the version that starts to feel like two products. Worth deciding deliberately rather than by default. This is about form, not substance. A Deep review will often surface more or different findings, and it may take longer. That difference is the point. It should show up as better review content, never as a different-looking review. --- ## 1. Naming ### Proposal - **Control noun:** Review depth - **Level 1**, today's review: **Standard** - **Level 2**, the new one: **Deep** - **Reserved above:** name and shape both TBD. Specialist is one candidate, a genuinely deeper level is another ### Why depth rather than effort **Effort describes something we only partly control.** It implies reasoning time and compute spend, but the model is chosen separately through [model selection](https://docs.gitlab.com/user/gitlab_duo/model_selection/), and model selection will itself become per level (see [section 4](#4-model-selection)). So the compute a review actually consumes is co-determined: we decide which models are available at each level, the customer picks within that. That creates a labeling problem, and not a hypothetical one: Deep will expose the full model catalog, so a customer can pick a cheap model there and get a review labeled as high effort while comparatively little compute was spent. Effort varies within a level. Depth does not. **Depth stays true in that case.** What we control unambiguously, and what changes between levels no matter which model runs, is how much context we gather and send: the diff, surrounding files, the Orbit graph, history. The same reasoning rules out "Balanced," which is otherwise a tempting middle label. Balanced implies a compute-versus-quality tradeoff that the customer has already overridden via model selection. ### Why Standard and Deep - **Standard, not Low or Basic.** Today's review is the floor, and it will be the default for most users. A magnitude word at the bottom of the scale tells customers their normal review is the weak one. A competitor shipped magnitude labels in preview and renamed both levels within weeks of general availability, which suggests they hit the same problem. Basic is worse still: it is the canonical deficient-tier word, and Basic / Advanced / Premium reads as a pricing ladder, which is a live confusion for us given we genuinely gate features by tier. - **Deep, not Advanced.** "Advanced Duo Code Review" is fine as a feature name, but as a *level value* next to Standard it has the same SKU smell. Deep is also the word the market and our own eval prompts already reach for. - **Headroom.** Nothing ladders convincingly above "deep," which is one reason most of the market ships two levels. That is an argument against paying for a third slot now by picking a weaker word for the second, not an argument that a third tier can never exist. If one arrives it might be a different kind of review, such as the domain-agent routing in #21524, or it might be a genuinely deeper one that needs a new word. Standard / Deep forecloses neither, and we do not have to solve it in this issue. ### Internal naming Keep the internal and external names the same. A public name that differs from the internal one means maintaining a translation layer indefinitely, and it makes the code harder to reason about for anyone reading it against the docs. Open question: whether the API field is `review_depth` or namespaced under the flow. --- ## 2. In the merge request Prototype: quick action dropdown, and a level badge in the Reviewers list. ### What works - The badge next to GitLab Duo in the Reviewers list is the right home. It treats depth as a property of that reviewer's assignment rather than as a merge check, so it shapes how you approach the review instead of reading as a gate to clear. - Showing which level ran, after the fact, is a real differentiator. Almost nothing else on the market does it. ### How it works **Two levels ship: Standard and Deep.** The mockups show two in the quick action and three in settings, so the design should settle on two. ### What needs deciding **What the levels communicate.** One mockup leads with price ("Cheaper, efficient review" / "Expensive, deeper analysis"), the other with work ("How much work Duo puts into an automatic review"). Worth picking one frame and using it everywhere. Recommendation: lead with what the user gets and mention cost second, since leading with "Expensive" invites the reaction that the good review is the one they cannot afford. **What happens when the level is omitted?** `/request_review @GitLabDuo` with no level should presumably fall back to the configured default, but that needs stating. **Can the level be changed after a review has run?** The prototype shows a re-run affordance next to the badge. If a Standard review has already posted comments and the author escalates to Deep, do we replace, append, or thread? This overlaps with Intelligent Follow-up Reviews ([#21620](https://gitlab.com/groups/gitlab-org/-/work_items/21620)). **Who can escalate?** Author, any developer, or restricted? Cost controls suggest this may need to be governable. --- ## 3. In settings Prototype: two variants, radio buttons shown only when automatic reviews are on, or a dropdown always visible and disabled when off. ### How it works **The default does not change.** Standard stays the default for existing and new projects, and Deep is opt-in. This is more than a UI preference: Standard is flat-rate and Deep is usage-based, so a changed default would move every existing customer onto usage-based billing without them asking. The mockup shows a higher level preselected, which should be corrected as the design is finalized. ### Recommendation Prefer the always-visible dropdown. Hiding the control when automatic reviews are off makes the setting undiscoverable for teams who use manual reviews only, and the level still applies to those. ### What needs deciding **Cascade behavior.** Automatic reviews already cascade instance to group to project. Depth should cascade the same way. Does a project override an instance default, or can an instance lock it? **Helper text.** The current copy, "Reviews logic, tests, and conventions alongside blocking problems," describes one level but sits below the whole control. It should be per-level, so a user can compare. --- ## 4. Model selection [Model selection](https://docs.gitlab.com/user/gitlab_duo/model_selection/) is currently per feature: Code Review has a model. That stops being sufficient once levels exist, because the levels bill differently and therefore offer different models. ### How it works - **Standard bills a flat rate**, so its model list stays as it is today. Existing customer selections carry forward unchanged. - **Deep does not bill a flat rate**, so organizations get access to the full catalog of available models for it. - **Deep defaults to Standard's current default model.** Holding the model constant out of the box means the difference a user experiences when they first try Deep is the depth itself, not a model change. It also makes the two directly comparable side by side. - **Selections are independent per level.** The lists differ, and choosing a model for Deep has no effect on Standard. - This applies to GitLab.com, Self-Managed and [Self-Hosted](https://docs.gitlab.com/administration/gitlab_duo_self_hosted/) alike. ### Proposal Restructure model selection so Code Review is a header with its levels underneath, each carrying its own model options: ``` Code Review Standard [model, current list] Deep [model, full catalog] ``` Cost implications of a given model are already surfaced in the model selection window, so they do not need separate treatment here. ### What needs deciding - Whether a group can pin the model at one level while leaving the other open, and whether an instance can lock either --- ## 5. Flow enablement **Depth levels will be built as separate foundational flows.** That is how flows are constructed and it is not in question here. The problem is presentational: foundational flows are enabled individually today, so without intervention that implementation detail surfaces as a set of admin toggles, and the mental model becomes "which review flows do I have" rather than "how deep should reviews be." ### Proposal - **One user-facing concept: Code Review Flow.** Enabling it makes every depth level available. The separate flow definitions behind it are not something an administrator should have to know about or manage. - **Depth presents as configuration, not as a set of features to switch on.** - **Levels can still be individually disabled as a cost control.** An administrator who never wants Deep to run should be able to turn it off at group or instance level, and the option should then disappear from the quick action rather than fail at request time. This is a deliberate exception to the point above, and it should be framed as spend control rather than as feature enablement. ### What needs deciding - How the unified presentation maps onto the separate flows underneath: whether enabling Code Review Flow enables all of them, and whether the per-level disable acts on the flow itself or on a setting layered above it - Where the per-level disable lives, alongside the default selector or in a separate cost section - What a user sees when they request a level their group has disabled - Whether a third tier, if it arrives, follows the same pattern --- ## Decisions needed | # | Question | Owner | Decision | |---|---|---|---| | 1 | Depth or effort as the control noun | Product | `Depth` | | 2 | Level names | Product + UX | `Standard` & `Deep` | | 3 | Settings variant, radios or dropdown | UX | | | 4 | How unified Code Review Flow enablement maps onto the separate flows underneath | Engineering + UX | | ## Related - [Advanced Duo Code Review: Specialized Agents Framework (#21524)](https://gitlab.com/groups/gitlab-org/-/work_items/21524) - [Intelligent Follow-up Reviews (#21620)](https://gitlab.com/groups/gitlab-org/-/work_items/21620) - [Duo Code Review UX discussion (#619414)](https://gitlab.com/gitlab-org/gitlab/-/work_items/619414) ## Prototype Screenshots {width=622 height=600} {width=900 height=346} {width=900 height=586}