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 seesprogram_manager, a program owner seesportfolio_head, a manufacturing specialist seescmc_process_scientistandformulation_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:
- 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.
- My open questions: the research questions you own in this program.
- My evidence board: your pins, rendered per licence with attribution lines (how to pin evidence).
- 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
| Symptom | Cause | Fix |
|---|---|---|
| The picker is missing | you hold viewer, or no program persona | viewers have no workbench role; ask an owner or lead for the persona your work needs |
| A role you expected is not offered | none 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 picker | the role’s personas do not intersect yours, or the program is not one of your memberships | choose 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 back | a workbench role is set for this program | choose 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 started | choose a role; the next run reads “working as <role>” |
Related
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