Skip to main content

ADR-0008: AI-Authored PR Narration (Tour Mode)

Note (2026-07-08), framed by ADR-0019: the sharpest objection to Stet's whole premise — a human reading AI-written code — is that AI multiplies output, so there is "more to read" at day's end. Tour mode is Stet's first-class answer, and this reframes it: reducing reading burden is a load-bearing design constraint, not a nicety. Guided reading order, risk flags, scroll-to-stop, the minimap (ADR-0002), and emoji-verb triage (ADR-0005) exist to make the human read less, and read the right things first. Every reading-surface feature should pass that test.

Context and Problem Statement​

Reading order is the unsolved problem of code review: a diff is presented alphabetically by file, not in the order a human should understand it. When the author is a human, you can't demand they explain the reading order. When the author is an AI — as it always is in Stet — you can.

We must decide whether AI-authored PRs are required to produce a structured walkthrough, and how the app consumes it.

Decision Drivers​

  • Comprehension is the product. Stet exists to make reading AI-written code tractable; guided reading order is core, not a nicety.
  • The author can be compelled. Since the AI authors the PR, narration can be a required output artifact with a defined schema.
  • It doubles as the review skeleton. Each narration stop is a natural place to stet or mark up (ADR-0006).
  • Native, calm presentation. The walkthrough should drive the canvas (scroll-to-stop, highlight range), consistent with the viewer posture (ADR-0002).
  • Graceful for non-AI PRs. Human-authored or externally-created PRs won't have narration; the app must still function.

Considered Options​

  • Option A: Require a structured walkthrough artifact from every AI-authored PR; render it as a first-class "Tour rail" that drives the canvas. Generate on-demand narration for PRs that lack it.
  • Option B: Show the PR description as prose only; no structured narration.
  • Option C: Generate narration lazily/on-demand for every PR at view time, and never require it as an authored artifact.

Decision Outcome​

Chosen option: Option A — a required, structured narration artifact for AI-authored PRs, rendered as a first-class Tour rail. The schema is an ordered list of stops, each with: a file + line range, a "why" (what changed and the reasoning), and a risk flag. The right-hand Tour rail lists the stops; selecting one scrolls and highlights the range in the canvas. For PRs that arrive without narration (human-authored, external), Stet generates it on demand via the LLM at view time, clearly labeled as generated rather than authored.

Consequences​

  • Good, because reading order becomes an explicit data structure, directly serving comprehension.
  • Good, because the stop list doubles as the review skeleton — each stop is a markup anchor (ADR-0006).
  • Good, because on-demand generation means every PR gets a tour, authored or not.
  • Good, because the rail drives the canvas natively (scroll/highlight), reinforcing the viewer posture (ADR-0002).
  • Bad, because we must define and version a narration schema and validate that agents emit it (ADR-0004 adapters must surface it).
  • Bad, because generated narration for large external PRs has cost/latency and quality variance.
  • Neutral, because narration quality depends on the model; the schema constrains shape, not correctness.

Confirmation​

  • AI-authored PRs (via Stet's dispatch) include a narration artifact conforming to the stop schema (file+range, why, risk flag).
  • The Tour rail renders stops and, on selection, scrolls + highlights the range in the canvas.
  • PRs lacking narration get labeled on-demand generation.
  • Each stop can carry review markup that feeds back into ADR-0006.

Pros and Cons of the Options​

Option A: Required artifact + first-class Tour rail (+ on-demand fallback)​

  • Good, comprehension-first, doubles as review skeleton, universal coverage.
  • Bad, schema definition/validation and generation cost.

Option B: Prose description only​

  • Good, trivial.
  • Bad, forfeits the core comprehension feature; no reading order.

Option C: On-demand only, never required​

  • Good, uniform handling.
  • Bad, wastes the fact that our agents author the PR and could emit narration directly; recomputes what could be authored once.

More Information​

Narration is produced by the harness adapters (ADR-0004) as part of a dispatch (ADR-0006) and rendered in the canvas/Tour rail (ADR-0002). See SPEC-0002.