# ADR-0059: OSHUN Research-to-Practice Journey Model

**Status**: Accepted  
**Date**: 2026-03-24  
**Authors**: OSHUN Product, OSHUN Design, OSHUN Web Engineering  
**Reviewers**: Tara, Arete, Veritas, Nisaba leads  
**Supersedes**: N/A  
**Superseded by**: N/A

## Context and Problem Statement

The PRD and gap-analysis documents repeatedly say the same thing: OSHUN should
not let research terminate as isolated reading.

The intended product behavior is stronger:

- grounded material should be traceable through Nisaba and the shared Sophia
  substrate
- contemporary questions should be clarified through Veritas when needed
- that grounded material should hand off into Tara and Arete rather than dying
  inside a notebook
- Library should preserve the thread so users can return to it deliberately

Before this task, the repo had the necessary primitives but no canonical
journey:

- Library already stored saved articles, passages, assistant excerpts, and
  notebooks
- Nisaba already modeled `claim_grounding`, `virtue_study`, compare workspaces,
  and notebook launches
- Veritas already exposed research and claim routes
- Tara and Arete already exposed practice and commitment entry points

But none of that was published as one shell-level answer to the question: "How
does grounded study become lived practice?"

That left a product gap. Teams could point at domain capabilities, but the shell
still lacked one shared model for the handoff from research into embodied
follow-through.

## Decision Drivers

- **Embodiment over accumulation**: OSHUN should turn grounded study into lived
  change, not just better archives.
- **Traceable grounding**: source-aware interpretation must remain visible
  through the journey, especially before practice advice is offered.
- **Shell continuity**: Library should preserve research continuity, not merely
  store disconnected items.
- **Cross-domain clarity**: Tara, Arete, Veritas, Nisaba, assistant, and Library
  need explicit roles instead of incidental link-outs.
- **Implementation leverage**: web Library, future mobile work, and QA need one
  typed journey contract they can all reuse.

## Considered Options

### Option 1: Leave research-to-practice implicit in collections, saves, and assistant prompts

**Description**: keep the flow distributed across Library copy, domain entry
points, and assistant suggestions without a canonical contract.

**Pros**:

- Lowest implementation cost.
- Avoids adding another shell model.

**Cons**:

- Leaves the core handoff from grounding into practice unowned.
- Makes it easy for research to stay archival instead of embodied.
- Gives QA and future surfaces no shared definition to verify against.

### Option 2: Model research only as a Nisaba or Sophia workbench flow

**Description**: treat research as a study-only lane and let practice handoffs
remain out of scope.

**Pros**:

- Matches source-grounded notebook patterns from competitor research.
- Easier to contain inside one domain/workbench metaphor.

**Cons**:

- Conflicts with the PRD requirement that Tara and Arete become better in the
  presence of grounded study.
- Makes OSHUN feel like a research tool beside a contemplative product rather
  than one integrated system.
- Fails the product thesis that the shell should help users live with more
  clarity and intentionality.

### Option 3: Publish an explicit research-to-practice journey model and render it on Library (Chosen)

**Description**: define one four-stage shell journey from saved thread selection
through grounding, synthesis, embodiment, and durable preservation; publish it
in shared navigation contracts; map it into web actions; and render it as a
first-class Library rail.

**Pros**:

- Makes the research-to-practice handoff executable.
- Gives Library a stronger continuity role than "saved items page."
- Keeps source grounding visible before practice recommendations are made.
- Produces one contract reusable by docs, web, QA, and later mobile work.

**Cons**:

- Adds another cross-domain journey model that future work must honor.
- Requires discipline so this model does not get mistaken for the separate
  story-to-source or assistant-led continuity work.

## Decision Outcome

**Chosen option**: Option 3.

### Normative Rule

OSHUN owns one canonical `Research to practice` shell journey.

Its question is:

> How should grounded study change what the user does next?

That journey is not complete when the user has merely read, saved, or sourced a
thread. It is complete only when the shell has preserved the path from grounded
material into Tara, Arete, and a durable resume point.

### Stage Rule

The normative stage order is:

1. `Name the question`
2. `Ground and synthesize`
3. `Turn into practice`
4. `Save the loop`

### Stage Semantics

#### 1. Name the question

Library is the canonical entry surface for choosing one live thread instead of
accumulating more disconnected saves.

At this stage, the shell may use:

- Library saved items or collections to identify the thread
- Veritas when the thread is a live claim or current question

The output is one selected thread worth grounding and carrying forward.

#### 2. Ground and synthesize

Grounding routes through Nisaba's source, compare, commentary, and notebook
surfaces, with the shared Sophia substrate standing behind that grounding
behavior.

The shell should then use the assistant to compress the grounded material into
one readable synthesis note without losing the source-aware posture.

The output is one grounded interpretation fit for practice translation.

#### 3. Turn into practice

Once the thread is grounded, the shell must make two handoffs:

- Tara for contemplative or ritual translation
- Arete for behavioral commitment

This stage exists to prevent grounded reading from ending as abstract
understanding only.

The output is one Tara practice link and one Arete next step explicitly tied to
the thread.

#### 4. Save the loop

Research-to-practice is only durable if the user can return to it later.

This closing stage should preserve:

- one Arete reflection note when useful
- one notebook or Library resume point that keeps the sources and practice
  thread connected

The output is a resumable record rather than a dead end.

### Surface Rule

- `Library` is the canonical structural surface for entering and preserving the
  journey.
- `Veritas` helps bound the question when the thread is contemporary or
  contested.
- `Nisaba` is the canonical grounding surface.
- `Tara` and `Arete` are the canonical embodiment surfaces.
- `Assistant` may help synthesize grounded material, but does not replace the
  source-grounding requirement.

### Contract Publication

The shared research-to-practice model lives in
`libs/oshun/navigation/src/research-practice-journey.ts`.

The web action mapping for that model lives in
`apps/oshun/web/src/navigation/research-practice-journey.ts`.

The current web rendering of that model lives in
`apps/oshun/web/src/components/library/ResearchPracticeJourneyRail.tsx`.

## Scope Boundaries

- This ADR defines the shell-level research-to-practice journey, not a full
  Sophia workbench or source-authoring system.
- It does **not** replace the later `story-to-source`, `sky-to-text`, or
  `assistant-led continuity` journey work.
- It does **not** require a standalone Sophia customer route; Sophia remains a
  shared substrate behind the grounding layer in this slice.

## Architecture Implications

- shared navigation code should expose typed research-to-practice stages and
  handoffs
- Library should make the journey actionable instead of treating it as an
  implied collection metaphor
- practice recommendations should remain downstream of grounded study rather
  than bypassing it
- future mobile and assistant work can reuse the same stage contract instead of
  inventing local copies

## Acceptance Criteria

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

1. A canonical ADR defines the research-to-practice journey model.
2. Shared navigation code publishes the same stage and handoff model.
3. The web Library surface reflects that model as actionable continuity
   guidance.
4. The shipped model makes Nisaba grounding, Tara practice, Arete commitment,
   and Library preservation explicit.
5. Tests verify the shared model, web action mapping, Library rendering, and
   Library handoff behavior.

## Related Decisions

- `docs/adr/ADR-0059-oshun-customer-information-architecture-and-tara-centered-spine.md`
- `docs/adr/ADR-0060-oshun-nisaba-first-class-customer-domain.md`
- `docs/adr/ADR-0064-oshun-daypart-cross-domain-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/research-practice-journey.ts`
- `apps/oshun/web/src/navigation/research-practice-journey.ts`
- `apps/oshun/web/src/components/library/ResearchPracticeJourneyRail.tsx`