Skip to main content

ADR-0006: Feedback Review Model — Markup Compiles to One Coherent Brief

Context and Problem Statement​

The core loop of Stet is: a human marks up code and prose (comments, emoji, strike-throughs, scribbled suggestions, voice notes), then submits feedback, which dispatches an agent that opens a pull request. The central design question is the granularity and timing of dispatch.

Dispatching one agent per comment the instant it is made would produce a swarm of conflicting PRs racing on the same files. Never dispatching until everything is perfect would kill the loop. We must decide how markup accumulates and how it turns into agent work.

Decision Drivers​

  • Coherence over chaos. Related feedback on the same change should be handled together, by one agent, in one PR.
  • Editorial rhythm. Marking up is a reading activity; dispatch should be an explicit, deliberate act (like submitting a GitHub review), not a side effect of each keystroke.
  • Intent capture. Emoji/comment verbs (ADR-0005) carry structured intent that must survive into the agent's brief.
  • Entanglement is real. Within one review, some items are independent and some depend on each other; the compile step must decide what is one task vs. several.
  • Recoverability. When the agent misses, replying with more feedback must be easier than dropping to a terminal (ADR-0002).

Considered Options​

  • Option A: GitHub-review model — markup accumulates as a pending review; an explicit Submit compiles it into a structured brief and dispatches one coherent workflow → one PR.
  • Option B: Per-comment dispatch — each marked item immediately spawns an agent.
  • Option C: Fully manual — the human writes a free-text brief; markup is just annotation.

Decision Outcome​

Chosen option: Option A — the GitHub-draft-review model. Markup accumulates into a pending review with no side effects. On Submit, Stet compiles the entire marked-up review into a structured brief: each item carries its verb (ADR-0005), location (file + range), and any text/voice/scribble intent. A compilation step (itself LLM-assisted) groups items into one or more workflow invocations — the default is one coherent PR per submitted review, splitting only when items are clearly independent. Iteration happens by replying to the PR with more feedback, which re-enters the same loop.

Consequences​

  • Good, because one review → one coherent PR avoids conflicting, racing agents.
  • Good, because Submit is an explicit, calm editorial act consistent with the viewer posture (ADR-0002).
  • Good, because structured briefs preserve verb intent and precise locations for the agent.
  • Good, because "reply with more feedback" is a first-class recovery path.
  • Bad, because the compile step (one task vs. several) is genuine product/AI design and a place bugs will hide.
  • Bad, because a large review may map imperfectly to a single PR; splitting heuristics need iteration.
  • Neutral, because the brief format becomes a stable internal contract between the review UI and the dispatch engine (ADR-0004/0005).

Confirmation​

  • Markup produces no dispatch until an explicit Submit.
  • Submit yields a structured brief containing, per item: verb, file+range, and captured intent (text/voice/scribble).
  • A submitted review dispatches one workflow (one PR) by default, splitting only for clearly independent items, with the rationale surfaced to the user.
  • Replying to a resulting PR with new markup re-enters the loop against the same branch/PR.

Pros and Cons of the Options​

Option A: GitHub-review model (accumulate → Submit → compile → dispatch)​

  • Good, coherent, deliberate, intent-preserving, recoverable.
  • Bad, compilation/splitting is hard; brief format must be carefully specified.

Option B: Per-comment dispatch​

  • Good, immediate, simple to implement.
  • Bad, conflicting PRs, wasted compute, no coherence; unusable at scale.

Option C: Manual free-text brief​

  • Good, no compile step to build.
  • Bad, throws away the structured markup that is the product's whole point.

More Information​

The brief is consumed by the workflow executor (ADR-0005) and harness (ADR-0004), and its results are narrated via Tour mode (ADR-0008). See SPEC-0002.