Skip to main content
info

This feature is in development. CYOD is a planned extension of the Deep Dive system that allows flexible, cross-category exploration.

Choose Your Own Deep Dive (CYOD) Idea

A developer-facing blueprint for adding a flexible, round-by-round deep-dive mode where a student can switch categories between rounds while the AI preserves full session context. CYOD reuses the proven handler trio pattern and living ledger architecture, extending the Deep Dive system with cross-category flexibility.

1. Purpose and Fit​

CYOD reuses the proven Deep Dive stack and ledger patterns, but removes the fixed "one category for four rounds" rule. Each round, the student picks any category. The AI builds on the complete Q and A trail from earlier rounds to generate the next question and interpretive summary. This aligns with the session-anchored, ledger-first approach already documented for Movement 1 and Deep Dives, including context reconstruction and token observability.

2. Terminology

  • Adventure: one flexible deep-dive run inside an existing session where categories may change each round.
  • Round: one cycle of generate questions, select one, reflect, save, and capture AI metadata.
  • Category: any of the five Movement 1 lenses plus Production Lab where available.

3. Data Model​

Leverage existing ledgers but add a minimal container for variable-length, mixed-category paths.

New tables
-- Container for a flexible, mixed-category deep-dive run
create table deep_dive_adventures (
id uuid primary key default gen_random_uuid(),
session_id uuid not null references rts_sessions(session_id) on delete cascade,
user_id uuid not null,
title text,                       -- optional user label
started_at timestamptz not null default now(),
ended_at timestamptz,
is_complete boolean not null default false
);

-- Per-round entries within an adventure
create table deep_dive_adventure_rounds (
id uuid primary key default gen_random_uuid(),
adventure_id uuid not null references deep_dive_adventures(id) on delete cascade,
session_id uuid not null,         -- convenience for joins and RLS
user_id uuid not null,
sequence_index int not null,      -- 1, 2, 3, ...
chosen_category text not null,    -- e.g. "Spark of Inquiry"
answered_question_id uuid,        -- pointer into questions log
user_reflection text not null,
interpretive_summary text,        -- AI synthesis for the round
model_used text,
prompt_token_count int, response_token_count int,
thinking_token_count int, total_token_count int,
thought_summary text,
created_at timestamptz not null default now()
);

Reuse existing logs​

  • Continue logging generated questions to deep_dive_followup_questions_log with session_id, round_number and categoryfields. These patterns already exist and are stable.
  • CYOD rounds simply point to their chosen question via answered_question_id.
  • Movement-level and standard deep-dive tables remain unchanged for backward compatibility.

RLS​

Copy existing RLS patterns. Scope all selects and inserts by user_id and session_id, same as Movement 1 and current deep dives.

4. API surface

Follow the proven "handler trio" style, adapted for a flexible flow.

  1. POST/api/movement1/cyod/startAdventure
Input: { session_id, optional_title }
Output: { adventure_id }
Notes: Validate user ownership. Verify Movement 1 synthesis exists to mark "completed foundation" as the starting anchor.

  2. POST /api/movement1/cyod/generateQuestions
Input: { adventure_id, session_id, next_category, sequence_index }
Server does:

    • Load topic and full reflection trail from all previous CYOD rounds plus prior Movement 1 or Deep Dive traces to build context, using the snippet pattern already in the docs for context concatenation.
    • Call Gemini with a category-specific system prompt and schema to return an interpretive summary plus structured questions.
    • Log every question to deep_dive_followup_questions_log with category = next_category.
Output: { interpretive_summary, question_groups or questions[], token_usage, thought_summary }.

  3. POST /api/movement1/cyod/saveRound
Input: { adventure_id, session_id, sequence_index, chosen_category, answered_question_id, user_reflection, ai_metadata }
Server does:

    • Persist to deep_dive_adventure_rounds.
    • Ensure sequence continuity.
Output: { ok: true }.

  4. POST /api/movement1/cyod/generateAdventureSynthesis
Input: { adventure_id, session_id }
Server does:

    • Pull the entire multi-category round trail in order.
    • Generate a cross-category synthesis and optional "next paths" recommendation.
Output: { synthesis_text, token_usage, thought_summary }.

Authentication, session validation, and RLS mirror the Deep Dive guide's standard patterns.

5. Prompting Strategy​

  • System instruction: keep each category's intent, tone, and constraints from the existing Deep Dive category prompts, but tell the model that the category may change each round and that it must weave prior reflections into each new interpretive summary.
  • Context block: Topic plus an ordered "Reflection Trail" with pairs of Round N → Category → Question → Student Reflection, matching the Movement 1 pattern for context building.
  • Schema: reuse category-specific JSON schemas already used in deep dives, but allow either a single question list for the chosen category or grouped subcategories where that category uses sub-lenses.
  • Observability: capture token counts and thought summaries to the round record, consistent with existing mechanics.

6. UI​

Add a single React page for CYOD. The component reuses the "single page component pattern" and mechanics panels used in deep dives. Mechanistic loader and AI metadata panel already exist in deep-dive UIs and should be reused here for consistency. Key UI elements:

  • Header: session topic plus adventure title.
  • Round picker: shows current sequence index and history.
  • Category chooser: five primary lenses plus Production Lab, rendered as cards with short intent blurbs.
  • Generate button: calls generateQuestions.
  • Interpretive summary: display as a labeled, generated artifact.
  • Question list: list or subcategory groups, choose one, then reflect.
  • Mechanics panel: token usage, thinking summary, cumulative log.
  • Synthesis: end-run option to synthesize cross-category insights and "next paths".

Dashboard integration:​

  • Add "Start Adventure" CTA in the Deep Dive Generators area of the student dashboard. Display active adventures with progress and a resume action. Dashboard patterns are already defined.

7. Flow Examples​

Start
Student clicks "Start Adventure" from the dashboard. Server creates deep_dive_adventures row. Round 1
Student picks "Spark of Inquiry". Generate questions with full Movement 1 trail as context. Save response to deep_dive_adventure_rounds with sequence_index = 1. Round 2
Student switches to "Puzzles and Unknowns". Generate with the entire trail, which now contains R1 content from Spark. Save as sequence_index = 2. Repeat as desired. End with cross-category synthesis when the student clicks "Synthesize Adventure".

8. Migration Plan​

  1. Create the two new tables with RLS policies mirroring reflection_rounds.
  2. No changes to the existing deep-dive tables that support fixed-category runs. CYOD coexists with those tables and flows.
  3. Add minimal indexes:
create index on deep_dive_adventure_rounds(adventure_id, sequence_index);
create index on deep_dive_adventure_rounds(session_id);

9. Telemetry and Research​

  • All standard metadata is already captured by the ledger approach.
  • Add optional cross-category analytics for "switch patterns" per adventure.
  • Export formats can reuse the existing student and research facing exports detailed in the Deep Dive dev guide.

10. Security and Privacy​

  • Reuse the documented RLS posture and session scoping across all new tables.
  • No model-side data persistence. All AI outputs stored in Supabase, with token usage tracked in round rows for observability.

11. Acceptance Criteria​

  • Start, continue, and complete an adventure inside a single session.
  • Category can change every round without breaking context integrity.
  • AI questions and interpretive summaries are grounded in the entire cross-category trail.
  • Token usage and thought summaries are captured and visible each round.
  • End-of-adventure synthesis summarizes the whole path and suggests next routes.
  • Dashboard shows active adventures and completion state.

12. Developer Notes and References​

  • CYOD intentionally follows the same handler pattern and UI conventions as fixed deep dives to reduce cognitive load for maintainers.
  • Use the existing context-build snippet pattern from Movement 1 to assemble trails across rounds.
  • Keep category strings aligned with the canonical set used by current deep-dive handlers and docs to avoid mismatches.

Further Reading​