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