Disciplines · Decisions (ADRs)

ADR-0062: OSHUN Assistant-Led Continuity Journey Model

The PRD already defines the consumer assistant flow at a system level and the web shell relationship model already defines Assistant as the global continuity layer rather than a peer structural route.

Accepted · 2026-03-24
9sections6 minread
Markdown source
On this page

Status: Accepted
Date: 2026-03-24
Authors: OSHUN Product, OSHUN Design, OSHUN Web Engineering
Reviewers: Shell, Iris, and Assistant leads
Supersedes: N/A
Superseded by: N/A

Context and Problem Statement#

The PRD already defines the consumer assistant flow at a system level and the web shell relationship model already defines Assistant as the global continuity layer rather than a peer structural route.

The codebase also already had important assistant building blocks:

  • a shell-local assistant engine, intent model, action router, and response formatter under libs/oshun/shell-assistant/*
  • a global assistant invocation event under apps/oshun/web/src/navigation/assistant-entry.ts
  • a global assistant UI under apps/oshun/web/src/components/assistant/AssistantPanel.tsx
  • cross-domain assistant summaries, domain switching, and saved assistant excerpts already present in shell concepts and Library data

But there was still no canonical shell-level answer to the question:

How should the assistant carry the user's current surface into the right next destination without losing context?

That gap mattered because Assistant was already treated as a continuity layer in shell IA, but not yet as an explicit cross-domain journey with bounded stages, typed handoffs, or a concrete UI that showed how continuity should move from invocation to handback and preservation.

Decision Drivers#

  • Assistant must act as continuity, not detached chat: the shell IA already says assistant inherits context and hands users back into product surfaces.
  • Context transfer must be explicit: the invoking surface and entry source should survive assistant open and the opening turn.
  • Cross-domain answers need structure: overview, grounding, and next-step help should resolve into real handoffs, not open-ended conversation.
  • Preservation matters: assistant exchanges should be able to become durable Library excerpts or Activity follow-up anchors.
  • Implementation leverage matters: docs, QA, web, and later mobile or Iris work need one typed continuity contract.

Considered Options#

Option 1: Leave assistant continuity implicit in shell IA and assistant code#

Description: keep the assistant as a global layer and rely on the existing assistant engine, UI, and navigation rules without publishing a dedicated journey model.

Pros:

  • Lowest implementation cost.
  • Reuses the current assistant surface directly.

Cons:

  • Leaves the assistant continuity promise untyped and untestable.
  • Gives no normative stage order for web, QA, or future mobile work.
  • Makes handback and preservation behavior easy to regress into generic chat.

Option 2: Treat assistant continuity as a Library-only preservation feature#

Description: model assistant continuity only through saved assistant excerpts and transcript preservation, without defining the invocation and handoff stages that precede preservation.

Pros:

  • Builds on existing Library concepts.
  • Keeps the durable-save story simple.

Cons:

  • Misses the invocation and handback behaviors that make assistant a continuity layer in the first place.
  • Treats assistant continuity as archival rather than active orchestration.
  • Does not explain how current-surface context should guide the live exchange.

Option 3: Publish an explicit assistant-led continuity journey model and render it inside the global assistant panel (Chosen)#

Description: define one four-stage shell journey from current-surface invocation through bounded request framing, memory-aware and grounding-ready answer shaping, real destination handback, and durable preservation; publish it in shared navigation contracts; map it into web assistant actions; render it in the assistant panel; and preserve the invocation source from shell entry.

Pros:

  • Makes the assistant continuity promise executable in one typed shell model.
  • Turns Assistant from a general chat affordance into a visible continuity workflow.
  • Preserves invoking-surface context while still resolving into product routes.
  • Produces one reusable contract for docs, QA, web, and later mobile work.

Cons:

  • Adds another cross-domain journey model that later work must respect.
  • Requires discipline so assistant-led continuity stays distinct from daypart, research-to-practice, story-to-source, and sky-to-text journeys.

Decision Outcome#

Chosen option: Option 3.

Normative Rule#

OSHUN owns one canonical Assistant-led continuity shell journey.

Its question is:

How should the assistant carry the user from this surface into the right next destination without losing context?

That journey is not complete when the assistant merely opens. It is complete when the shell has preserved the invoking context, bounded the need, shaped a handoff-ready brief, and exposed one durable continuity trace after the user is handed back into the product.

Stage Rule#

The normative stage order is:

  1. Inherit the current context
  2. Bound the need
  3. Ground and shape the answer
  4. Hand back and preserve

Stage Semantics#

1. Inherit the current context#

Assistant is the canonical entry surface, but it must begin from the current shell or domain context rather than a blank conversation state.

This stage exists to preserve:

  • the invoking surface
  • the entry source
  • the live screen or task context that motivated the assistant open

2. Bound the need#

Once assistant is open, the shell should quickly turn the interaction into one bounded continuity request such as:

  • overview or reorientation
  • next-best-move guidance
  • grounding request
  • return-path or preservation help

This stage ensures the conversation stays aimed at continuity rather than drifting into generic chat.

3. Ground and shape the answer#

The assistant should then make its working posture visible by shaping the reply through:

  • memory scope
  • source-aware grounding when needed
  • one concise assistant brief that can hand back into the product

This stage is where the assistant becomes the shell's meaning layer rather than just a command relay.

4. Hand back and preserve#

The journey must end in:

  • one concrete product destination
  • one durable assistant excerpt or related continuity trace
  • one visible follow-up path when Activity needs to reflect the outcome

This keeps the assistant from becoming a closed conversational cul-de-sac.

Surface Rule#

  • Assistant is the canonical live continuity surface.
  • current shell surfaces remain the continuity origin and return destination.
  • Library is the canonical preserve surface for saved assistant excerpts.
  • Activity may reflect resulting follow-up anchors but is not the preserve surface.

Contract Publication#

The shared assistant continuity model lives in libs/oshun/navigation/src/assistant-continuity-journey.ts.

The web action mapping for that model lives in apps/oshun/web/src/navigation/assistant-continuity-journey.ts.

The current web rendering of that model lives in apps/oshun/web/src/components/assistant/AssistantContinuityJourneyRail.tsx.

The current web assistant-source carry-over lives in apps/oshun/web/src/components/ShellLayout.tsx.

Scope Boundaries#

  • This ADR defines the shell-level assistant continuity journey, not the full Iris memory system, Psyche embodiment runtime, or Sophia retrieval stack.
  • It does not replace deeper assistant disclosure, persona switching, or evidence-UI backlog items.
  • It does not require every assistant outcome to become a Library item; it defines the canonical preserve path when continuity should survive.

Architecture Implications#

  • shared navigation code should expose typed assistant-continuity stages and handoffs
  • the assistant panel should render those stages as actionable continuity UI
  • shell assistant entry should preserve invocation source into the panel
  • Library assistant excerpts should remain a first-class preserve destination
  • future mobile, Iris, and grounded-answer work can reuse one canonical assistant continuity definition instead of inventing local copies

Acceptance Criteria#

V1-UX-010 is complete only when all criteria below are true:

  1. A canonical ADR defines the assistant-led continuity journey model.
  2. Shared navigation code publishes the same stage and handoff model.
  3. The web assistant maps that model into concrete query, route, and preserve actions.
  4. The shipped assistant UI reflects invoking context, bounded assistant asks, handback destinations, and Library preservation.
  5. Tests verify the shared model, web mapping, shell source carry-over, assistant-panel rendering, and browser-level assistant handoff behavior.
  • docs/adr/ADR-0061-oshun-web-shell-relationship-model.md
  • docs/adr/ADR-0064-oshun-daypart-cross-domain-journey-model.md
  • docs/adr/ADR-0065-oshun-research-to-practice-journey-model.md
  • docs/adr/ADR-0066-oshun-story-to-source-journey-model.md
  • docs/adr/ADR-0067-oshun-sky-to-text-journey-model.md

References#

  • docs/releases/v1/specs/web-app-admin-v1-prd.md
  • docs/releases/v1/reports/unified-product-gap-analysis-and-nisaba-integration-report-2026-03-22.md
  • libs/oshun/navigation/src/assistant-continuity-journey.ts
  • apps/oshun/web/src/navigation/assistant-continuity-journey.ts
  • apps/oshun/web/src/components/assistant/AssistantContinuityJourneyRail.tsx
  • apps/oshun/web/src/components/assistant/AssistantPanel.tsx