Eve library

V1-AWEB-100 — Admin Workspace Ergonomics Spec

Spec

Revision 1

On this page

Implementation spec for the Phase 17.10 admin workspace ergonomics. Goal: define ergonomics for repeated approvals, bulk actions, copy-heavy inspection, and split-screen multitasking.

Reference: as-is#

The current admin app supports single-row decision flows well (per-row approve / reject / escalate works on every queue) but falls short on:

  • Repeated approvals. No "approve next 10 in a row" flow; operators click 10 rows individually.
  • Bulk actions. Inbox is the only panel with formal bulk actions today; trust-safety lists, support inbox, privacy queue, and review queue do not bulk-act.
  • Copy-heavy inspection. Long evidence lists, audit timelines, and citation metadata require copy-paste into external tools (Slack, Linear); the admin app offers no per-section "copy as markdown" helpers.
  • Split-screen multitasking. The shell does not optimise for two-column operator workflows (e.g., review on the left, policy bundle reference on the right).

Design principles#

  1. Repeated approvals are a first-class verb. Every single-row decision action surface ships an "approve next" shortcut that advances the queue cursor and opens the next row in the action rail without navigating away.
  2. Bulk acts via the canonical bar (V1-AWEB-095). The AdminTableBulkActionBar already exists; the work in V1-AWEB-100 is to declare per-panel bulk actions where they make policy sense.
  3. Copy is a per-section affordance. Every readable section (audit timeline, evidence list, decision rationale, policy bundle JSON) ships a "copy as markdown" button in its header.
  4. Split-screen is hash-driven, not OS-driven. Operators open a second panel on the right via ?compare=<workspace>:<entity-id> URL parameter; the shell renders the second panel inside an AdminCompareView (V1-AWEB-094).
  5. Cursor persistence across pages. When the operator acts on a row, the cursor stays where it was; the queue refresh does not reset to the top.

Repeated approvals#

Add <ApproveNextShortcut /> (new) to every single-row decision panel:

  • Renders a button labelled Approve next ⏎ after a successful approval.
  • Pressing the button (or hitting Enter while focus is on the button) advances the URL hash detail id to the next row in the current queue's filter set, opens that row in the detail panel, and re-focuses the action rail's primary decision button.
  • Works for V1-AWEB-085 comparative verdicts, V1-AWEB-086 hallucination accept, V1-AWEB-087 consent uphold, V1-AWEB-088 voice / avatar verified.

Bulk actions per panel#

Per-panel bulk actions to declare (read with V1-AWEB-095's AdminTableBulkActionBar):

  • UnifiedInboxPanel — already has bulk actions; keep.
  • PrivacyRequestQueuePanel — bulk-assign-owner, bulk-extend- deadline (re-uses existing single-row endpoints in a client-side loop with progress indicator).
  • SupportCaseInboxPanel — bulk-tag, bulk-reassign-queue.
  • ReviewPackageList — bulk-delegate.
  • AppealQueueList — bulk-tag.
  • RetentionManagementPanel — no bulk action (every legal hold needs individual confirmation per V1-AWEB-099).
  • ResearchIntegrityQueuePanel — bulk-tag.
  • CitationValidationWorkspacePanel — bulk-mark-validated (only when all selected have status pending and the operator's scope permits).

Copy-as-markdown#

<CopyAsMarkdownButton sectionId={id} /> (new) renders a small icon button in the section header; on click it serialises the section's data into markdown via a per-section serialize() function and writes to the clipboard. Sections to wire:

  • Audit timeline (V1-AWEB-097) — chronological list with actor + timestamp.
  • Evidence lists (every panel that lists citations / evidence refs).
  • Decision rationale (V1-AWEB-085/086/087/088/089 review decision banners).
  • Policy bundle JSON (PolicyBundleEditorPanel).

Split-screen via URL#

?compare=<workspace>:<entity-id> enables a right-edge AdminCompareView mounted by the shell. The second panel is read-only; actions on the right panel are disabled. Useful for:

  • review left, policy bundle reference right;
  • moderation left, prior-decision history right;
  • support case left, related billing record right.

Cursor persistence#

The queue panel's useAdminQueueState() hook (V1-AWEB-094) persists the focused row id in URL hash; on queue refresh after an action, the cursor stays on the next-after-acted row, not the top.

Implementation deliverables#

  1. apps/oshun/admin/src/components/ApproveNextShortcut.tsx + .module.css.
  2. apps/oshun/admin/src/components/CopyAsMarkdownButton.tsx
    • .module.css + per-section serialize helper file (apps/oshun/admin/src/lib/copy-as-markdown.ts).
  3. apps/oshun/admin/src/lib/use-admin-queue-cursor.ts — cursor-position hook used by useAdminQueueState().
  4. Bulk action declarations on the named panels above.
  5. Split-screen rendering in AdminShell.tsx (reads ?compare query param, mounts AdminCompareView on the right).
  6. Tests: cursor persistence unit test, copy-as-markdown unit tests (~15 cases), Playwright admin-workspace-ergonomics.spec.ts covering repeated approval, bulk action progress, copy-as-markdown, and split-screen URL.

Acceptance criteria#

  • Every single-row decision panel ships an "Approve next ⏎" button after a successful approval.
  • Every named queue ships its declared bulk actions; progress indicators show during multi-row execution.
  • Copy-as-markdown renders in every audit timeline / evidence list / decision rationale / policy bundle section.
  • ?compare=... mounts a second read-only panel on the right via AdminCompareView.
  • Cursor persists across queue refresh after an action.
  • Cursor + copy + bulk Playwright spec passes.