Skip to main content

SPEC-0002: Feedback Review

Overview​

Feedback review is the core human loop of Stet: the user marks up code and prose (comments, emoji reactions, strike-through/scribble suggestions, voice notes), then submits the review, which compiles the entire markup into a structured brief for dispatch (SPEC-0003). It also specifies Tour mode — the AI-authored guided walkthrough that both aids comprehension and serves as the review skeleton.

This spec realizes ADR-0002 (viewer posture), ADR-0005 (declarative verbs), ADR-0006 (accumulate → submit → compile → one coherent PR), and ADR-0008 (PR narration). It builds on SPEC-0001 (canvas, inbox, forge). It does not cover the container/harness/workflow execution that consumes the brief — that is SPEC-0003.

Requirements​

Requirement: Pending Review Accumulation​

Markup SHALL accumulate into a pending review with no side effects until the user explicitly submits it. No agent is dispatched by the act of marking up.

Scenario: Marking up without dispatch​

  • WHEN the user adds comments, emoji, suggestions, or voice notes to a file or PR
  • THEN the items are collected into a pending review indicator, and nothing is dispatched until an explicit Submit.

Scenario: Discarding a pending review​

  • WHEN the user discards a pending review
  • THEN all accumulated markup is cleared and nothing is dispatched.

Requirement: Anchored Comments and Suggestions​

The application SHALL let the user attach comments and suggestions to a precise location (file + line range) in the canvas, including free-text suggestions that express intended changes.

Scenario: Commenting on a range​

  • WHEN the user selects a line range and adds a comment
  • THEN the comment is anchored to that file + range and appears in the pending review and beside the code.

Requirement: Emoji Verb Vocabulary​

The application SHALL provide an emoji reaction vocabulary in which each emoji is a structured verb bound to a workflow definition (per ADR-0005), not decoration. A curated default verb pack SHALL be shipped, and the binding SHALL be data, not hardcoded.

Scenario: Applying a verb​

  • WHEN the user reacts to a function with 🐛
  • THEN the reaction is recorded as the "investigate" verb bound to its workflow in the active verb pack, anchored to the code, and included in the pending review.

Scenario: Default verb pack​

  • WHEN the app loads
  • THEN a curated set of verbs (e.g., 🐛 investigate, 🎨 refactor-ugly, ❓ explain, 🔥 delete) is available from a default pack loaded as data.

Requirement: Voice and Scribble Annotations​

The application SHALL support voice annotations (press-and-hold to speak, transcribed to comment text) and gesture-based strike-through/scribble suggestions on code, converting each into anchored intent in the pending review.

Scenario: Voice note​

  • WHEN the user holds the voice key and speaks while a range is selected
  • THEN the speech is transcribed and stored as a comment anchored to that range.

Scenario: Scribble-to-suggest​

  • WHEN the user strikes through a span of code with a pencil/trackpad gesture
  • THEN the gesture is captured as a suggestion (intent to remove/replace) anchored to that span.

Requirement: Submit Compiles a Structured Brief​

On Submit, the application SHALL compile the entire pending review into a structured brief in which each item carries its verb, location (file + range), and captured intent (text/voice/scribble). The brief SHALL be the contract handed to the dispatch engine (SPEC-0003).

Scenario: Compilation on submit​

  • WHEN the user submits a pending review containing several marked-up items
  • THEN Stet produces a structured brief listing every item with its verb, file+range, and intent, ready for dispatch.

Requirement: One Coherent PR Per Review​

A submitted review SHALL default to a single coherent workflow invocation (one PR), splitting into multiple only when items are clearly independent, and SHALL surface the grouping rationale to the user.

Scenario: Default single grouping​

  • WHEN a review's items relate to the same area of change
  • THEN they are compiled into one workflow invocation targeting one PR.

Scenario: Independent items split​

  • WHEN a review contains clearly independent items (e.g., a doc typo and an unrelated refactor)
  • THEN the compiler may produce multiple invocations, and the rationale for the split is shown to the user before dispatch.

Requirement: Iterate by Replying​

The application SHALL let the user reply to a resulting PR with additional markup, re-entering the review loop against the same branch/PR rather than requiring a terminal.

Scenario: Follow-up feedback​

  • WHEN a dispatched PR misses the mark and the user adds more markup and submits
  • THEN the new brief is dispatched against the same PR/branch as a follow-up.

Requirement: Tour Mode Narration​

The application SHALL render an AI-authored PR walkthrough as a first-class Tour rail of ordered stops — each with a file + range, a "why," and a risk flag — that drives the canvas (scroll + highlight) on selection. For PRs lacking authored narration, the app SHALL generate it on demand, labeled as generated.

Scenario: Touring an AI-authored PR​

  • WHEN the user opens a PR that Stet dispatched
  • THEN the Tour rail lists ordered stops from the PR's narration artifact, and selecting a stop scrolls and highlights the corresponding range in the canvas.

Scenario: Narration for an external PR​

  • WHEN the user opens a PR that has no authored narration
  • THEN Stet generates a walkthrough on demand and presents it labeled as generated rather than authored.

Scenario: Stops as review anchors​

  • WHEN the user is at a tour stop
  • THEN they can add markup at that stop, which enters the pending review like any other anchored item.