Skip to content

Ship UX — guidance-first redesign (draft)

Direction for making Ship the guided conductor Rafael opens daily — not a status dashboard you have to interpret.

Problems today

Pain Example
Scan-heavy Freeze, Away, Agents, Needs you, Stuck, Initiatives, Detail — all compete for attention
No single “what now” WRITING-DAILY + PORT-* tickets look the same; agent gates use jargon (waiting_on: agent)
Detail pane is passive Steps live in test_goal text; no copy-paste prompts, no “do this in Cursor” button
Pipeline is abstract 9 stage chips without “you are here because…”
Agents are a footnote Small pills; automation on/off buried; ops vs writing not grouped

North star

One hero card answers: What needs me right now? Everything else is supporting context.

┌─────────────────────────────────────────────────────────────┐
│  NOW: Write 2 articles · WRITING-DAILY                      │
│  Why: Calendar gap since Aug 4 · automation ON              │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │ Open Cursor │  │ Copy prompt  │  │ Pause automation │  │
│  └─────────────┘  └──────────────┘  └──────────────────┘  │
│  Steps: 1 status → 2 drafts → 3 finalize-batch              │
└─────────────────────────────────────────────────────────────┘
│  Later: PORT-12 staging test (when writing done)            │
│  System: Ops pulse OK · €4.20 left · not frozen             │
└─────────────────────────────────────────────────────────────┘

Information architecture (target)

flowchart TB
  subgraph hero [Hero — Now]
    N[Primary action card]
    P[Copy prompt / deep link]
  end
  subgraph queue [Queue — Soon]
    L[Needs you list ranked]
    A[Agent runs + toggles]
  end
  subgraph context [Context — Collapsed]
    I[Initiatives board]
    R[Receipts timeline]
    W[Wallet / freeze / away]
  end
  hero --> queue --> context

Ranking rules for “Needs you”

  1. Human-blocking (approve test, merge, budget) — always top
  2. Agent handoff (writing backfill, topic refill) — second, with playbook
  3. Stuck / soak failure — red, with last receipt link
  4. Everything else — board only

Phase plan

Phase 1 — Quick wins (this sprint)

  • [x] Writing automation toggle on Agents strip + Ship API + portfolio cron respect
  • [x] Human labels everywhere (waiting_on → “Draft in Cursor”, not agent)
  • [x] WRITING-DAILY detail template: numbered steps + copy block for backfill prompt
  • [x] Collapse wallet/stuck into a single “System status” row when green
  • [x] App shell — Now / Queue / All work / System sidebar
  • [x] Hero Now card + ranked queue

Phase 2 — Guided detail pane

  • [x] Ticket drawer with playbook / detail / receipts tabs
  • [x] Compact All work list (pipeline in drawer only)
  • [x] Preview slot for staging tickets (link card in drawer; opens preview in new tab)

Phase 3 — Conductor mode

  • [x] Queue view with status groups
  • [x] Ticket-type playbooks in drawer
  • [x] Keyboard: n next, Esc close drawer, / search, ? shortcuts help
  • [x] Mobile: hamburger nav; full-screen drawer
  • [x] Sprint 1–3 UX (2026-08): ticket rows, queue badge, collapsible initiatives, writing strip, system operator/advanced split, toasts
  • [ ] Discord parity: same “Now” text as Ship hero (single source in notify templates)

Phase 4 — Proactive guidance

  • [x] Graph tab — React Flow canvas (Shep features-canvas parity): repo → initiative → ticket, Dagre LR layout, pan/zoom, CI pills, topic queue nodes
  • [x] Ship suggests next ticket after mark_done / merge / approve (toast + auto-advance drawer)
  • [x] Writing agent: topic/backfill preview from latest notify payload (hero, drawer, graph TopicNode)
  • [x] Worker output gate — schema enforcement on worker output before any file or Forgejo write, with a bounded repair loop (Fullsend ADR-0022; scripts/lib/worker-output-gate.mjs; see agent-patterns-borrow §11)
  • [~] NormalizedEvent router — envelope, normalizers and gate evaluation shipped in shadow mode: decisions are recorded to router_decisions, nothing is ever dispatched (ship/normalized-event.js, ship/event-router.js). Live auto-dispatch is still open (ship-normalized-events.md)
  • [x] Ops pulse issues → inline fix links in System operator summary (Sprint 4)

Component sketches

Agent strip (evolved)

Agent Status Toggle Primary CTA
Writing daily BACKFILL_READY ON/OFF Open WRITING-DAILY
Ops pulse ok — View last run
Weekly digest sent Mon — —

Ticket detail — writing playbook

## Your move
Calendar is 2 days behind. Topics are ready.

1. In portfolio repo, ask Cursor: **Run backfill writing workflow**
2. Review drafts in `scripts/.writing-backfill-drafts.json`
3. Run `npm run writing:finalize-batch`

[Copy prompt] [Pause automation]

Metrics (informal)

  • Time from open Ship → start Cursor session (target: < 30s)
  • Needs-you items dismissed without opening detail (should ↓)
  • Writing toggle usage (expect pauses during travel / focus weeks)