Skip to Content
PlatformHow-to guidesChoose your workbench role

How to choose your workbench role

Use this guide when you join a program and want your home screen, your rail and your twin’s toolset arranged for the desk you sit at: medicinal chemistry, DMPK and toxicology, CMC, quality, program management and the rest of the fifteen. You start on the persona home with the picker “Choose your workbench role”; you end on the role home with the header line “Working as: <role>”. Choosing needs only your own session; nothing about your permissions changes. Every surface here carries the status word designed until the R4 gates pass.

One sentence sits on the picker and is worth keeping in mind: “Workbench roles change what you see first, never what you may do.” What you may approve, sign, write or read is your persona’s, and it is exactly the same before and after you choose.

Prerequisites

  • A program persona other than viewer. The picker offers only the roles whose personas you hold: a scientist sees the scientific roles, a quality reviewer sees qa_reviewer, a program lead sees program_manager, a program owner sees portfolio_head, a manufacturing specialist sees cmc_process_scientist and formulation_scientist. Viewers have no workbench role and no harness.
  • Nothing else. There is no permission to request and no setting to enable.

Open the program home

/p/<slug>/home shows the persona home until a workbench role is set: “Decisions waiting for you”, the twin panel, and in the header the picker Choose your workbench role, an inline segmented list (a listbox when the list is long). The picker suggests a first choice for your persona (qa_reviewer, program_manager, portfolio_head or cmc_process_scientist); the suggestion is copy, not a stored value, and until you choose the agent runs under your persona’s neutral harness.

Choose a role

Select a role in the picker. The choice is applied at once: the header reads “Working as: Medicinal chemist”, an inline confirmation line appears under the picker, and the page rearranges without leaving it. The web app calls PATCH /me/settings with {workbench_role: {<program_id>: "medicinal_chemist"}}; the API checks that the program is one of yours and that the role’s personas intersect yours (422 workbench_role_not_held otherwise, shown beside the picker), stores the value per program in your settings and audits workbench_role.set. Pick another role the same way at any time.

Use the persona home

To go back to the persona home, choose Use the persona home in the same picker. The web app calls PATCH /me/settings with {workbench_role: {<program_id>: null}}; the program’s entry is removed, the change is audited workbench_role.set with new: null, and the home shows “Choose your workbench role” again (contract 12.3, recorded 2026-09-16). Fact (verified in web/components/workbench/role-picker.tsx:128-131, web/lib/content.ts:293-294, api/app/schemas/console.py:269 and api/app/routers/me_settings.py:50-57): the picker offers Use the persona home whenever a role is set, the settings schema types the map as dict[uuid.UUID, str | None], and the router pops the program’s entry for a null value | Consequence: this step is built; the picker confirms with the inline line “Persona home. Choose a workbench role any time.” The feature as a whole keeps the status word designed until the R4 gates pass.

Read the role home

Four regions in fixed order:

  1. Today’s decisions: the items waiting for you, the record types of your role first, signatures first within them, and “Also waiting” collapsed under them with a count.
  2. My open questions: the research questions you own in this program.
  3. My evidence board: your pins, rendered per licence with attribution lines (how to pin evidence).
  4. My program in this role’s terms: a status strip written in your role’s labels, every sentence linked to the record it comes from and marked “from program records”; on the seeded demo program it also carries “illustrative”.

Below the fold: the twin panel and “What your twin remembers” (how to read it). The rail promotes your role’s products and folds the rest under All records; nothing is hidden, and section labels change to your words (“SAR hypotheses” for a chemist, “Study designs” for a DMPK scientist) while every page heading keeps the record’s contract name with your label as the subtitle. Setup and Organization stay under More by permission; the program manager’s rail promotes Setup.

Change it later

The header line “Working as: <role>” carries Change, which expands the same picker in place. When a lead set the role for you, the line reads “Set by <Name> on <date>. Change” instead, and you may still change it yourself. A change never switches a run that is already going; the next run wears the new harness.

Assigning a role for someone else

A program lead or owner (program.members.manage) opens Setup › Members and chooses Assign workbench role on the member’s row. The row expands with the role list and a required reason; submitting calls PUT /programs/{program_id}/workbench-roles/{user_id} with {workbench_role_key, reason}, writes the member’s setting for this program, and audits workbench_role.assign with the lead as actor and the member as target. The member’s header reads “Set by <Name> on <date>. Change”. The same 422 workbench_role_not_held applies when the member does not hold a persona the role maps to.

When nothing is set

Your twin and the console still work. The agent wears the neutral persona harness of your persona (scientist, quality reviewer, program lead, program owner or manufacturing specialist; the most senior when you hold several), the fallback is audited once as workbench_role.default_applied, and the home keeps showing “Choose your workbench role”. The fallback never writes the setting, so nothing is chosen on your behalf.

Troubleshooting

SymptomCauseFix
The picker is missingyou hold viewer, or no program personaviewers have no workbench role; ask an owner or lead for the persona your work needs
A role you expected is not offerednone of its personas is yours (for example cmc_process_scientist needs manufacturing_specialist or scientist)the role list is filtered by your personas; a lead can add a persona through Setup › Roles
422 workbench_role_not_held beside the pickerthe role’s personas do not intersect yours, or the program is not one of your membershipschoose a role that is offered; the error names the key
The header says “Set by <Name>a lead assigned the role with a reason (audited)choose Change to pick your own
You want the persona home backa workbench role is set for this programchoose Use the persona home in the picker; the line “Persona home. Choose a workbench role any time.” confirms it
Proposals read “working as Scientist”no workbench role was set when the run startedchoose a role; the next run reads “working as <role>

Source: PRODUCT-CONTRACT.md sections 12.1, 12.2, 12.3 and 12.10; PRODUCT-PLAN.md Part 9 sections 3.1 to 3.3; api/app/auth/personas.py (PERSONA_VERSION = 3); api/app/db/models/org.py and twin.py (the USER_SETTING_* constants); docs/lib/content.ts (consoleCopy.chooseWorkbenchRole, consoleCopy.workingAs, consoleCopy.setBy); decisions/0027-workbench-roles-as-ux-and-harness-layer.md; decisions/0034-inline-interaction-no-popups.md

Last updated on