Inbox V3 — The Clarity Pass (Superhuman, not Outlook)

May contain stale references

This document was audited on 2026-06-22 and contains references that need updating: line numbers throughout are stale (file is 812 lines, not 855+). Cross-check critical details against the current codebase before relying on them.

Status: DRAFT (under /autoplan review) Branch: claude/compassionate-golick-2d4aaf Builds on: docs/designs/inbox-is-the-product.md (V2, shipped) and the live apps/webapp/src/pages/inbox.astro + components/inbox/*.

Problem (one sentence)

The inbox V2 shipped the data model and the cockpit, but the surface still reads like Outlook: every row carries ~11 competing visual objects, and one /inbox route serves two different humans (the clerk who works items and the supervisor who watches a team), so both see controls that aren’t for them.

The two users — make the split structural, not conditional

	Clerk (CSR / operator)	Supervisor (manager / order desk)
Job	Work my queue, one item at a time	Watch the team, keep SLAs green
Question on open	”What’s mine? What can I grab?"	"Who has what? What’s breaching?”
Primary action	claim → review → submit	assign, escalate, report
Ideal surface	fast list, keyboard-driven	table / kanban with people columns

Today these are merged behind ?view= params and capability checks inside one page. The clerk sees a disabled Dashboard button and a “Unified queue” tab they have no use for; the supervisor reaches their view through a URL param nobody discovers. The conflation is the root cause of the clutter — every band-aid control (scope dropdown, All tab, view toggle) exists to serve both users from one surface.

Decision: split the route

• /inbox → Clerk surface only. No supervisor controls, no disabled buttons, no ?view=. This is InboxCockpit.
• /team → Supervisor surface. First-class table + kanban (today’s SupervisorInboxRoot), team selector, SLA threshold, export. Gets its own left-rail nav entry, gated on inbox.view.team.
• A supervisor working their own queue uses /inbox like everyone else; /team is for the monitoring job, not a second copy of the list.

Server-side API gates already re-validate caps, so this is mostly routing: a new astro page that renders SupervisorInboxRoot + CockpitShell, and removal of the supervisor branches from inbox.astro.

The row — three signals, not eleven

Today InboxItemRow.tsx renders, per row: checkbox, source icon, sender, title, tier badge (T1/T2/T3), PO number, broker, duplicate flag, status badge, ”✓ Extracted” badge, ”✕ Error” badge, assignee label, SLA time. Eight of those are colored. The user cannot triage by scanning — they must read every row.

V3 row contents:

│ [sender]                    [title / subject]                    [time] │
└ left-edge SLA strip (3px, color only)

Three things: sender, title, time. The left-edge is a 3px vertical strip whose color encodes urgency/health, with zero text:

Strip color	Meaning	Token
transparent	no SLA threshold configured	—
green	plenty of SLA budget	--color-success
amber	approaching SLA	--color-warning
red	breached, or item in error state	--color-danger

Everything else moves to where it belongs:

Removed from row	New home
Status badge (new/in_progress/awaiting_review/submitted)	Group header — rows are already grouped by uxState; the header says “Awaiting Review (3)”, so the per-row badge is pure redundancy
✓ Extracted / ✕ Error badges	Strip color (error = red strip) + detail pane
Tier T1/T2/T3	Detail pane header
PO number	Detail pane (prominent)
Broker name	Detail pane
Assignee label	Detail pane. In the list, assigned simply = not in the “Available” queue. That IS the signal.
Source icon (email/upload/clone)	Removed from the scan path; upload/clone keep a tiny muted pip only

Exceptions that earn a per-row chip (rare, judgment-bearing, not a normal state): Dup? (amber — needs human check before claiming), Test (amber — changes how you treat the submission), Price mismatch (the one extraction exception worth surfacing pre-open). Nothing else.

Unread stays as the existing left dot + bold sender. New rows keep the subtle bg-blue-50/30 tint.

Naming — speak the operator’s language

Personal and Organization are data-model words, not operator words. A CSR thinks “my work” and “stuff I can grab,” not “the organization queue.”

Today	V3	Why
Personal	Mine	items assigned to me
Organization	Available	unassigned, anyone can claim
Branch	Branch: [name]	unchanged, already clear
All	All	supervisor-only, lives on /team now

Two string changes in InboxTabNav.tsx plus the smart-default logic in inbox.astro (which already routes an empty personal queue to the org queue — reword the comments, keep the behavior).

Queue counts — already computed, just unhidden

inbox.astro already computes queueCounts {user, organization, all} server-side and passes it to InboxCockpit. Render them inline on the queue pills:

Mine (3)     Available (12)

Counts are scoped to the current lifecycle view (so “Mine 3” matches what the Mine tab shows) and deliberately not narrowed by search/filter — they’re stable queue-size badges, not filtered-result counts. No new query.

Keyboard-first — make the shortcuts visible, not modal-only

The cockpit already has full keyboard nav (KEYBOARD_HINTS_LIST, the ? help modal). The gap is discoverability: today you only learn the keys by opening a modal. Superhuman teaches you in context.

• On the focused row, show ghost-text hints at the right edge in --om-surface-ink-3 at 10px: e archive · r review · z snooze. They appear on focus/hover, never shout, and vanish otherwise.
• Keep the ? modal as the full reference.
• / focuses search, hinted near the search box.

Pure additive UI, zero behavior change — the handlers already exist.

Toolbar — collapse three bands into one

Today, above the list: (1) tab nav, (2) search + lifecycle + date + dashboard + filters + refresh, (3) a collapsible filter drawer. For a clerk that’s too much chrome. V3 clerk toolbar:

1. Queue pills (always visible, with counts): Mine (3) · Available (12)
2. Search — one debounced input, no submit button
3. Lifecycle — Active / Archived / Trash as a compact icon-toggle group

Active filter presets become dismissible chips above the list (visible only when a preset is on), instead of living hidden in a drawer. The drawer stays for power users but isn’t the default surface. The supervisor toolbar (/team) is a separate component with team selector / SLA / export — not this one.

Status model — pick one source of truth

Two parallel status systems exist: raw item.status and derived item.uxState (deriveUxState). The row shows both — the raw badge plus the uxState group it sits under. V3: the group header is the status. The per-row badge is dropped for normal states; only the three exception chips above remain.

Scope — what is NOT in this plan

• No data-model changes. workItems schema, SLA fields, polling all stay.
• No detail-pane rework. The split-pane review surface is V2 and stays.
• No supervisor feature changes. /team is the existing SupervisorInboxRoot moved to its own route, not a redesign of it.
• No new endpoints. Queue counts and caps already exist server-side.
• Mobile detail layout, onboarding banner, dashboard internals: unchanged.

What already exists (leverage map)

Sub-problem	Existing code
Supervisor surface	components/inbox/SupervisorInboxRoot.tsx, CockpitShell.astro
Clerk list + keyboard	InboxCockpit.tsx, cockpit/lib.ts (KEYBOARD_HINTS_LIST, groupItemsByState)
Row	InboxItemRow.tsx (and cockpit/CockpitRow.tsx)
Queue counts	inbox.astro queueCounts (already passed as prop)
uxState grouping	lib/inbox/work-item-ux-state.ts deriveUxState
SLA color logic	getSlaDisplay in InboxItemRow.tsx (reuse the ratio→color map for the strip)
Tab rename	InboxTabNav.tsx tabLabel

Phases (ORIGINAL — superseded by the reframe below)

1. Route split → DEFERRED (see Phase-1 outcome)
2. Row simplification (hard strip) → DEFERRED (re-spec as density toggle)
3. Naming + counts → SHIP (premise-independent)
4. Toolbar collapse + keyboard hints → partial SHIP (keyboard hints only; toolbar collapse folded into the deferred clerk-surface work)

Success criteria

• A clerk on /inbox sees zero supervisor controls and zero disabled buttons.
• A row in the list shows exactly: sender, title, time, and a color strip (plus at most one exception chip). Measured by reading the rendered DOM.
• “Mine” and “Available” replace “Personal”/“Organization” everywhere a clerk sees.
• Queue counts visible on the pills without opening anything.
• A new clerk can discover e/r/z// without opening the ? modal.

---

/autoplan Review

Phase 1 — CEO Review (Strategy & Scope)

CEO Dual Voices — Consensus Table

═══════════════════════════════════════════════════════════════════════
  Dimension                              Claude   Codex   Consensus
  ─────────────────────────────────────  ───────  ──────  ──────────────
  1. Premise valid (clutter/role =       NO       NO      CONFIRMED-NO
     the real adoption blocker)?                          (unvalidated)
  2. Right problem to solve?             PARTLY   NO      DISAGREE→lean NO
  3. Route split reduces confusion?      NO       NO      CONFIRMED-NO
     (vs fragments dual-role supervisor)                  (needs design)
  4. Row strip preserves triage?         NO       NO      CONFIRMED-NO
     (tier/PO/broker are scan signals)                    (info debt)
  5. "Superhuman" is the right star?     NO       NO      CONFIRMED-NO
     (B2B work-queue ≠ consumer email)                    (cargo-cult)
  6. Alternatives explored?              NO       NO      CONFIRMED-NO
     (density toggle / progressive)                       (dismissed)
═══════════════════════════════════════════════════════════════════════

5/6 CONFIRMED concerns, 1 lean-negative. This is unusually strong cross-model agreement against the plan as written — it is a User Challenge, not a set of taste decisions.

CODEX SAYS (CEO — strategy challenge)

10 findings (2 critical, 5 high, 3 medium). Highlights:

• C1 (critical): Wrong root cause. Repo’s own docs/product/email-inbox-ux.md names the real adoption killers — false-positive noise (L77), lack of unified oversight/delegation (L104), duplicate work because Ordermatic can’t yet replace source-inbox actions (L160). Reframe around “queue trust” + “workflow replacement,” prove drop-off before spending a quarter on visual cleanup.
• C2 (critical): /inbox vs /team is clean for the designer, not the supervisor — who is a hybrid operator triaging their own queue while rebalancing others. Route split adds constant context switches + fragmented state. If you split, require instant mode-switch + preserved selection/filters.
• H3: “Superhuman” is the wrong north star for a B2B exception console. Replace with “high-trust order desk”; measure throughput, mis-triage, supervisor intervention — not elegance.
• H4: Row strip is information debt; same red strip = SLA breach OR extraction error collapses two different actions into one ambiguous cue. Don’t rely on color alone.
• H6: Density is a product capability, not a design failure — offer Focused/Dense, persist per-user, instrument which correlates with faster resolution.
• M9: Success criteria are UI assertions, not outcomes. Require claim-to-open time, items/active-hour, opened-then-abandoned %, before approval.

CLAUDE SUBAGENT (CEO — strategic independence)

10 findings (3 critical). Key independent code finding:

• F3 (critical): The clean-split premise is contradicted by the code. SupervisorInboxRoot’s ViewSwitcher already has a 'cockpit' mode and the supervisor table/kanban links point back to /inbox?inbox_view=.... The two surfaces are one continuum with a shared switcher today; the dual-role lead flips a view toggle in place. A route split forces a route change (/team→/inbox), losing scroll/filters/selection — for the most valuable operator.
• F1 (critical): No usage evidence row clutter is the blocker. For an ops tool the dominant risks are extraction accuracy, claim/submit latency, trust in AI output — not row density.
• F6 (critical): Tier IS the triage signal; PO/broker are how a CSR recognizes “the Walmart reorder” without reading the subject. Color-only strip fails ~8% colorblind. Honest version is a density toggle, not forced minimalism.
• Both models agree the surviving cheap wins: naming (Personal→Mine, Organization→Available), rendering existing queue counts, and in-context keyboard ghost-hints. Ship those independently; hold the route split + row strip.

What already exists (leverage map — CEO)

Sub-problem	Existing code	Implication
Clerk/supervisor “separation”	SupervisorInboxRoot ViewSwitcher has cockpit mode; links target /inbox	Surfaces already entangled — split is a refactor, not routing
Real adoption levers	docs/product/email-inbox-ux.md (trust, delegation, writeback)	The strategic moat is elsewhere
Cheap wins	InboxTabNav labels, queueCounts prop, KEYBOARD_HINTS_LIST	Shippable today, reversible, premise-independent

NOT in scope (CEO confirms, plus new deferrals)

• Detail-pane rework, data-model changes, supervisor feature changes (as written).
• New deferral flagged by both models: queue-trust / false-positive reduction and source-inbox workflow replacement — the likely real levers — are out of this plan and should be weighed against it, not buried under it.

Dream-state delta

CURRENT: shipped V2, cluttered row, conflated route. THIS PLAN: cleaner clerk list, split route, renamed queues. 12-MONTH IDEAL (per both models): a trusted order desk where CSRs stop falling back to Outlook because the queue is accurate and the workflow is complete — not merely prettier. This plan moves the cosmetic needle; it does not move the trust needle. The cheap wins (naming/counts/hints) are pure-positive; the contested half (split + strip) may be motion, not progress, on an unvalidated premise.

Premise Gate Outcome — REFRAMED SCOPE (user decision)

User chose: Reframe — ship cheap wins, hold bold half. Both models recommended this.

SHIP NOW (reversible, premise-independent):

• S1 — Naming. Personal→Mine, Organization→Available in InboxTabNav.tsx tabLabel. (Codex M8 caveat: confirm “Available” only labels items any clerk may actually claim; if claimability isn’t guaranteed, use “Unassigned.” Resolve in Design.)
• S2 — Queue counts on pills. Render existing queueCounts {user, organization} inline: Mine (3) · Available (12). Show count semantics so “12 but I see 4” confusion (Codex M8) can’t happen.
• S3 — In-context keyboard ghost-hints. Surface e/r/z// as muted ghost text on the focused row; keep the ? modal as full reference. Purely additive.

HOLD (deferred until unblock conditions met):

• H-Route-Split — blocked on: design the dual-role supervisor’s in-place cockpit↔team mode-switch (preserve scroll/filters/selection) AND untangle the shared ViewSwitcher (SupervisorInboxRoot already has a cockpit mode whose links point at /inbox?inbox_view=...). Not “just routing.”
• H-Row-Density — blocked on: (a) one piece of real CSR usage/qualitative data on what slows triage, and (b) re-spec as a Focused/Dense toggle (default Focused = 3-signal; Dense keeps tier/PO/broker/assignee), persisted per-user, instrumented. No color-only state (colorblind + SLA-vs-error ambiguity). No irreversible deletion of the data path.

Both models’ strategic note (logged, not actioned here): the larger adoption levers per docs/product/email-inbox-ux.md are queue trust (false-positive reduction), unified oversight/delegation, and source-inbox workflow replacement. Tracked as separate scope, weighed against (not buried under) this polish sprint.

Decision Audit Trail

#	Phase	Decision	Classification	Principle	Rationale
1	CEO	Run both dual voices	Mechanical	P6	Always run available voices
2	CEO	Premise (clutter/role = blocker) is unvalidated	—	—	Both models CONFIRMED-NO; surfaced at gate
3	CEO	Reframe to ship-cheap / hold-bold	User Challenge	user decision	User chose A at premise gate
4	CEO	Ship S1 naming	Auto (post-reframe)	P3/P5	Reversible string change, premise-free
5	CEO	Ship S2 counts	Auto	P3	Data already computed; just render
6	CEO	Ship S3 keyboard hints	Auto	P1/P5	Additive, zero behavior change
7	CEO	Defer route split	Auto	P6	Both models: not just routing + dual-role cost
8	CEO	Defer hard row strip; re-spec as toggle	Auto	P5	Reversible > irreversible on unvalidated premise

Phase 2 — Design Review (Dual Voices)

Design Consensus Table

═══════════════════════════════════════════════════════════════════════
  Dimension                              Claude   Codex   Consensus
  ─────────────────────────────────────  ───────  ──────  ──────────────
  1. Targets the live surface?           NO       NO      CONFIRMED-NO
     (S1/S2/S3 hit legacy flag-off files)                 (re-point cockpit)
  2. "Available" honest for the queue?   NO       NO      CONFIRMED-NO → "Unassigned"
  3. Count semantics unambiguous?        NO       NO      CONFIRMED-NO (add "N of M")
  4. Keyboard hints land on real keys?   NO       NO      CONFIRMED-NO (r,/ dead)
  5. Hint placement collision-free?      NO       NO      CONFIRMED-NO (right edge taken)
  6. A11y (contrast/aria) sufficient?    NO       NO      CONFIRMED-NO (10px ink-3 fails)
  7. Density-toggle default              Focused  Dense   DISAGREE → taste (deferred)
═══════════════════════════════════════════════════════════════════════

Key resolved design decisions

• N-1 Naming: Organization → Unassigned (not “Available”). Both flag “Available” over-claims claimability; repo already uses “Unassigned” preset and empty-state copy “No unclaimed orders.” Personal → Mine (unambiguous).
• QC-1 Counts: pill = stable queue total; when a filter/search is active, render a separate Showing N of M line (role="status" aria-live="polite"), mono/tabular digits. Never make the pill track filtered results.
• KH Hints: do NOT hint r (no binding) or / until wired. Prefer extending the always-on ListFooter legend (KEYBOARD_HINTS_LIST) over per-row right-edge hints (the right edge already holds Claim/snooze/SLA). If a focused-row hint is added, put it in the SLA/date column, focus-only, ≥12px, ≥4.5:1 contrast (the --om-surface-ink-3 token is a light-surface token; on the dark cockpit pane use text-white/45-55).
• DISAGREE (taste, deferred): density-toggle default — Claude=Focused (clean default), Codex=Dense (don’t strip scan signals from existing operators).

Phase 3 — Eng Review (Dual Voices)

Eng Consensus Table

═══════════════════════════════════════════════════════════════════════
  Dimension                              Claude   Codex   Consensus
  ─────────────────────────────────────  ───────  ──────  ──────────────
  1. Rename scope complete?              NO       NO      CONFIRMED-NO (6 surfaces)
  2. "N of M" has a trustworthy M?       NO       NO      CONFIRMED-NO (page vs total)
  3. "/" binding edge-case safe?         NO       NO      CONFIRMED-NO (IME/CE/modifier)
  4. withCount fits aria/tabular work?   NO       NO      CONFIRMED-NO (restructure)
  5. Test coverage sufficient?           NO       NO      CONFIRMED-NO (extract+test)
  6. SSR/hydration safe?                 YES      YES     CONFIRMED-YES (client:only)
═══════════════════════════════════════════════════════════════════════

Architecture note — the rename is a vocabulary migration, not a string swap

Six clerk-visible surfaces carry Personal/Organization, several abbreviated so a naive find/replace silently skips them:

1. InboxCockpit.tsx:624 QueueSwitcher (LIVE) — withCount('Personal'|'Organization')
2. InboxTabNav.tsx:25-32 tabLabel (legacy)
3. InboxSidebar.tsx:20-39 sidebar labels (legacy — missed by subagent first pass)
4. InboxToolbar.tsx:301-310 stats noun 'personal'/'org' (legacy)
5. InboxItemRow.tsx:253-266 All-tab origin chip — abbreviated 'Org', not “Organization”
6. InboxEmailRow.tsx:111-120 All-tab origin chip — the ACTUAL flag-off row path (!useWorkItems renders InboxEmailRow, per inbox.astro:855 / InboxPage.tsx:623) Fix (both voices): centralize queue/origin labels in ONE shared helper; every consumer reads from it so live and legacy can’t fork. Grep gate before merge: grep -rn "Personal\|Organization" components/inbox returns zero clerk-visible label hits.

”N of M” — define M before building (HIGH, both)

The cockpit has no trustworthy queue-total in scope: items.length is the loaded page (≤50, inbox.astro:617 offset), queueCounts ignores lifecycle/branch/search by design (inbox.astro:620-661), flatList is a client-only pre-debounce filter. Resolution: N = flatList.length (filtered); M = totalWorkItemCount (server count for the committed query) and ONLY after the query is server-synced; make copy page-aware when page>1 (Showing 51-100 of 120) or suppress the total until synced. Never compare against queueCounts. Gate the line on an active filter so the clean case stays clean.

”/” binding — guards required (HIGH, both)

Existing handler guards INPUT/SELECT/TEXTAREA only (InboxCockpit.tsx:302-305). HelpDrawer.tsx:99-103 already shows the correct pattern (adds isContentEditable). New branch, ordered before generic single-char branches:

} else if (e.key === '/' && !e.metaKey && !e.ctrlKey && !e.altKey) {
  e.preventDefault();
  searchRef.current?.focus();

Plus add if (e.isComposing || e.keyCode === 229) return; and target.isContentEditable to the top-of-handler guard. preventDefault only when actually focusing search.

withCount restructure (both)

withCount bakes label+count into one string → blocks per-pill aria-label and mono/tabular digit styling. Replace with structured option data {label, count, ariaLabel} (or a count-badge subcomponent); add optional ariaLabel to SegmentedOption (defaults to label; lifecycle/view switchers pass through unchanged). Keep the aria-live “N of M” node always mounted (empty when unfiltered) so SRs announce it.

Final — Corrected Shipping Scope + Implementation Tasks

The reframe (ship cheap wins) plus the design/eng corrections collapse the shippable work to a small, precise set. The original plan pointed at legacy files; the live target is the cockpit.

• T1 (P1, human ~2h / CC ~20m) — Centralized label rename. Add a shared queueLabel/origin-label helper; rename Personal→Mine, Organization→Unassigned across all 6 surfaces (cockpit QueueSwitcher, InboxTabNav, InboxSidebar, InboxToolbar stats, InboxItemRow 'Org' chip, InboxEmailRow chip). Grep gate must pass. Tests: helper unit + legacy-flag-off manual check.
• T2 (P2, human ~3h / CC ~30m) — “Showing N of M” filtered indicator. Structured count {label,count,ariaLabel} replaces withCount; mono/tabular digits; role=status aria-live=polite line, always mounted, filled only when a filter is active; M = server-synced totalWorkItemCount, page-aware (Showing 51-100 of 120), never queueCounts. Tests: formatFilteredCount unit (not-filtered/page1/page>1/unsynced/edges).
• T3 (P2, human ~2h / CC ~20m) — Wire / + footer hint. New guarded / branch (!meta/ctrl/alt, isComposing/keyCode 229, isContentEditable); add ['/', 'search'] to KEYBOARD_HINTS_LIST. Do NOT add r. Extract key dispatch to a pure helper for testing. Tests: ”/” guard matrix.
• T4 (P3, human ~1h / CC ~15m) — Pill a11y. Optional ariaLabel on SegmentedOption (defaults to label); "Mine, 3 items" / "Unassigned, 12 items".

Deferred (gated, not in this sprint)

• D-Route-Split — design dual-role supervisor in-place cockpit↔team mode-switch (preserve scroll/filters/selection) + untangle shared ViewSwitcher before any /team route.
• D-Density-Toggle — Focused/Dense segmented control, localStorage inbox:density, per-user later, instrumented (resolution-time by density). OPEN TASTE: default Focused (Claude) vs Dense (Codex, “don’t strip existing operators”). Blocked on one piece of real CSR usage data.
• D-Queue-Trust (strategic, separate scope) — false-positive reduction, delegation, source-inbox writeback per docs/product/email-inbox-ux.md — the likely real adoption levers.

#	Phase	Decision	Classification	Principle	Rationale
9	Design	”Available”→“Unassigned”	Auto	P5 (explicit/honest)	Both voices; over-claims claimability
10	Design	Counts: pill=total + “N of M” line	Auto	P1	Kills “12 but I see 4”
11	Design	Drop r hint; gate /	Auto	P5	Don’t teach dead keys
12	Design	Density default Focused vs Dense	Taste	—	DISAGREE → final gate (deferred work)
13	Eng	Rename = centralized helper, 6 surfaces	Auto	P4 (DRY)	Both voices; prevents fork
14	Eng	M = server total, page-aware	Auto	P1	queueCounts/items.length untrustworthy
15	Eng	/ IME+CE+modifier guards	Auto	P1	Real correctness bugs once reachable
16	Eng	Restructure withCount for aria/tabular	Auto	P5	Baked string blocks a11y
17	Eng	Extract pure helpers + unit test	Auto	P1	Handler currently untested