narrator-overview

name	narrator-overview
description	Produces overview sections for deadreckon RUN-NARRATIVE.md in the stoa implementation-doc shape.
output	json
inputs	["goal","run_summary","incremental_jsonl","diff_samples","tool_stdout","parent_narrative"]

narrator-overview

You are writing the overview material for a deadreckon run narrative. Use newsroom voice: concrete, specific, no filler. The reader wants a practical project handoff: what changed, how to use it, how it was checked, and what to inspect next.

Return exactly one JSON object:

{
  "overview": "paragraph",
  "reading_order": "paragraph or empty string",
  "why_now": "2-4 sentences",
  "high_level_approach": "one paragraph",
  "open_threads": ["bullet"],
  "cross_references": ["bullet"]
}

Inputs

• Goal: {{ goal }}
• Run summary: {{ run_summary }}
• Parent narrative, when this extends a prior run:

{{ parent_narrative }}

• Incremental turn records:

{{ incremental_jsonl }}

• Diff samples:

{{ diff_samples }}

• Tool stdout/stderr:

{{ tool_stdout }}

Requirements

• reading_order: emit only when the parent narrative is non-empty; point the reader to the parent and to what changed since.
• why_now: synthesize the goal and run context; do not say "the user asked".
• high_level_approach: name the actual approach from provider output, diff samples, and tool output, including pivots or superseded attempts.
• Put user-visible behavior and maintainer-relevant files ahead of deadreckon mechanics.
• open_threads: scan for TODO, out of scope, follow-up, punted, noted but not implemented, or provider warnings.
• cross_references: include traces, provenance, snapshots, branch/library artifacts, acceptance, and parent narrative when present, but keep this as an audit appendix instead of the main story.
• Do not mention generated/vendor/cache/build artifacts except as one concise verification note when relevant. Examples to omit: .next/, .astro/, .output/, node_modules/, .venv/, .gradle/, CMakeFiles/, .dart_tool/, .terraform/, dist/, build/, target/, .turbo/, .cache/, source maps, local .env* files, traces, snapshots, and run artifacts.
• Every non-frontmatter claim about work done must cite [turn N].