Skip to content

Narrative Agent Split Brain Dump

Created: 2026-05-29 07:32 UTC

Raw Notes

Right now agent.narrative.generateScenes is doing two jobs at once:

  1. generating the spoken narrative
  2. generating all scene semantics around it

Product flow should be:

  • Generate VO Script Preview needs only previewable voiceover text
  • Go To Scene Details needs the richer scene package

Separate the current narrative contract into:

1. NarrativePreviewScript

Purpose: generate only ordered scene voiceover sentences for preview.

Likely fields:

  • sceneId
  • index
  • text
  • estimatedDurationSec

2. NarrativeSceneDetails or final VoiceoverScriptJson

Purpose: take approved preview sentences plus context and derive:

  • caption
  • sceneQuery
  • recommendedVisualType
  • visualGenerationPrompt
  • voScriptSection
  • any reveal/slide hints needed downstream

That means preview becomes narrative-first, and scene details become semantic expansion after approval.

How It Should Play Out

For Generate VO Script Preview:

  • prepareRunStep
  • skip IntentAgent when the description is already explicit enough
  • skip KnowledgeOrchestrator when sources are uploaded-only
  • retrieve RAG context
  • run agent.narrative.generatePreviewSentences
  • persist preview payload
  • suspend at narrative-review

For Go To Scene Details:

  • resume from narrative-review
  • take approved preview sentences
  • run agent.narrative.expandSceneDetails
  • continue into visuals/slides/direction/compile

That is a cleaner HITL boundary than the current setup.

What Should Also Change Alongside It

  • Remove IntentAgent in preview mode when the request already contains stable videoName, description, and VO guidance.
  • Skip KnowledgeOrchestrator for uploaded-only runs.

Main Risks

  1. Semantic drift between step 1 and step 2. If step 2 is allowed to reinterpret the approved sentences too freely, the scene details may stop matching the preview. Fix: make step 2 consume approved sentences as hard input, not soft inspiration.

  2. Prompt duplication. If both steps independently reason over the same context, you may still pay too much. Fix: preview step should be narrow; expansion step should reuse persisted artifacts and only compute missing fields.

  3. Contract fragmentation. If the split is informal, downstream workflows get messy. Fix: introduce explicit schemas for:

  4. preview sentences
  5. expanded scene details

  6. final voiceover JSON

  7. Slide/reveal planning assumptions. Some current downstream logic may assume the narrative step already emits reveal-related fields. Fix: move those fields to expansion or slide-planning explicitly rather than leaving them ambiguously narrative-owned.

Architecture Recommendation

  • Step 1: generate PreviewVoiceoverScenes
  • Step 2: expand approved scenes into NarrativeSceneList / VoiceoverScriptJson

That keeps the approval boundary explicit.

Context Diagram

flowchart TD
  prepare["prepareRunStep"] --> previewMode{"Preview mode?"}
  previewMode -->|explicit request| skipIntent["Skip IntentAgent"]
  previewMode -->|uploaded-only sources| skipKnowledge["Skip KnowledgeOrchestrator"]
  skipIntent --> rag["Retrieve RAG context"]
  skipKnowledge --> rag
  rag --> previewAgent["agent.narrative.generatePreviewSentences"]
  previewAgent --> review["Persist preview and suspend at narrative-review"]
  review --> approval["User approves preview sentences"]
  approval --> expand["agent.narrative.expandSceneDetails"]
  expand --> visuals["visuals / slides / direction / compile"]