narratio/docs/internal/stage-analyze.md

Stage: analyze

Purpose

Generate the session recap artifact using configured Scriptorium artifact settings.

Inputs and Outputs

Inputs:

• transcript inputs as requested by selected artifact config (processed/normalized/trimmed/current recap, depending on pipeline.scriptorium.artifacts.session_recap.inputs)

Outputs:

• artifacts/session_recap.md

Boundaries

Owns:

• Selecting supported analyze artifact (session_recap only)
• Resolving transcript/reference inputs and vars
• Optional render-debug execution before run
• Main Scriptorium run and output promotion

Does not own:

• Transcript processing pipeline stages
• Archive publish/pointer behavior

Config Fields Used

• session.session_id
• session.campaign
• pipeline.workspace.root
• pipeline.scriptorium.binary
• pipeline.scriptorium.config_path
• pipeline.scriptorium.timeout
• pipeline.scriptorium.render_debug
• pipeline.scriptorium.artifacts.session_recap.*
  • enabled
  • prompt_id
  • profile_id
  • timeout
  • output_path
  • render_debug
  • inputs
  • vars

External Adapters Used

• Scriptorium adapter:
  • optional RenderArtifact (debug diagnostics)
  • RunArtifact (actual recap generation)

State and Manifest Behavior

• If pipeline.scriptorium is nil, stage returns success metadata with skipped=true.
• If no enabled artifacts exist, stage returns success metadata with skipped=true.
• If enabled artifacts exist but any artifact other than session_recap is enabled, stage fails.
• Uses run-local output/log/config/reports paths when run layout is enabled.
• Promotes canonical recap output and records adapter metadata.

Skip and Resume Behavior

• Runner-level skip applies when already succeeded and not forced.
• Forced reruns can stale downstream succeeded stages.
• Stage-local "skipped" metadata is distinct from runner-level stage status skip.

Failure Behavior

• Fails on missing required resolved inputs, invalid transcript inputs, render/run adapter failures, or validation-failed run results.

Tests to Inspect Before Changing

• internal/stage/analyze_test.go
• internal/adapters/scriptorium/subprocess_test.go

Architectural Invariants

• Analyze implementation supports only artifacts.session_recap as executable artifact.
• Optional inputs may be omitted; required inputs must resolve.
• Successful output must exist and be non-empty before promotion.