Surfacing --description content beyond the info popup

[fgrehm]

Context

--description / --description-file (#130) feeds the info popup, reachable via i. That works well when the description is a short addendum, but it falls short when the description is the entry point to the review.

I'm experimenting with an agent-driven review loop where the agent writes a description file (problem statement + protocol reminder for the reviewer) alongside an annotations file, then launches revdiff. The description is the first thing the I should read, not an optional aside. Today there's no way to surface it without me reminding to i which is something I keep forgetting.

I suspect this generalizes beyond agent flows - PR descriptions, release notes alongside a diff, "read me before reviewing" context for a teammate.

Options I've considered

A. Auto-open the info popup on startup (--show-info or implicit when --description* is set)

• Smallest change / blast radis
• It'd block the initial diff view and a modal feels heavy when the description is the point of the session
• it also doesn't help much on additional rounds of an iterative review

B. Render the description as a virtual file in the sidebar with a new flag

• Always-visible entry, no modal interruption
• Composes naturally with the existing markdown TOC pane
• Doubles as a persistent reference, re-readable any time without re-opening a popup
• More design surface: naming (_review.md? [notes]?), ordering (top of tree?), behavior when the tree is hidden and god knows what else
• The info popup keeps working unchanged for short blurbs and tree-hidden modes

What I'm looking for

A read on whether B is in scope and worth exploring, or if there's a third framing I'm missing.

Related

• Proposal: Add a --description cli flag so the agent can explain the diff to the user in a dedicated pane. #130
• The agent-driven flow this came out of is right below. It's the first pass on this flow, been testing it for a day or so

Agent skill

Click to view skill

---
name: revdiff-conversation
description: Two-way code review with revdiff. Trigger when the user wants the agent to walk them through changes inline AND collect feedback on the same lines — phrases like "review with me", "explain what you did and let me reply", "let's discuss the diff".
---

revdiff conversation loop

Turn-based, line-anchored conversation between agent and user, on top of a real diff. Agent writes annotations into a file. revdiff loads them inline. User edits, replies, adds their own. Quit returns the merged set. Repeat until quit-clean.

Protocol

Agent always prefixes its notes with [agent]. User prefixes nothing. Anything without [agent] is user content.

One-sided by design — user just types, agent does the bookkeeping. Always include this protocol in the description file so the user reads it before typing.

The loop

Pick a session id <sid> (timestamp like 20260507-1432). Reuse it for all three files in a round.

1. Write the annotations file at /tmp/revdiff-conv-<sid>.md. Every note starts with [agent] plus an intent tag — [agent][explain], [agent][question], [agent][must-fix], [agent][nit]. Without the prefix, the next round misreads it as user content. Lead with what was done and why on key lines. One or two sentences each.

2. Write the description file at /tmp/revdiff-desc-<sid>.md:

   • One short paragraph: what problem the change solves and the approach
   • The protocol reminder verbatim: "To reply to one of my notes, edit it in place — overwrite my text. To add your own note, just type. Don't add any prefix; everything without [agent] at the start is treated as yours."
   • Anything else worth knowing before reading

3. Launch revdiff in a stacked zellij pane, blocking until quit:

   zellij run --block-until-exit --close-on-exit <STACKED_LAYOUT_FLAGS> -- \
     revdiff --annotations=/tmp/revdiff-conv-<sid>.md \
             --description-file=/tmp/revdiff-desc-<sid>.md \
             --output=/tmp/revdiff-reply-<sid>.md \
             [ref]
   

   Replace <STACKED_LAYOUT_FLAGS> with whatever produces a stacked layout (zellij run --help).

4. Read the reply file at /tmp/revdiff-reply-<sid>.md. Same format as the input.

5. Reconcile by walking each note in the reply:

   • Body still starts with [agent] and matches the original → unchanged, ignore
   • Body still starts with [agent] but text differs → user edited in place, treat as user reply
   • Body does not start with [agent] → user content, address it
   • Note from the original file is missing → user dismissed/resolved it
   • No user content anywhere → done, stop

   Apply code changes, answer questions.

6. Next round (only if step 5 found user content). Fresh <sid>. The new annotations file:

   • Re-states [agent] notes for lines the agent still has commentary on (e.g. "made the change you asked for, here's what's different")
   • Adds [agent][question] notes anywhere a user reply needs more clarification
   • Does NOT carry forward unchanged or already-addressed notes from the previous round

   Loop back to step 2.

Stopping

Loop ends when a reply file has no user content — every note still has [agent] unchanged, no new non-[agent] notes. Summarize what landed across all rounds and stop. No "confirmation" relaunch.

Annotation format

## path/to/file.go (file-level)
[agent][explain] Extracted into its own module to reduce coupling with the request handler.

## path/to/file.go:43 (+)
[agent][explain] Switched to errors.Is() because the previous comparison broke wrapping.

## path/to/file.go:67-89 (+)
[agent][question] This loop allocates per-iteration. Pool the buffer, or is throughput not a concern?

## store.go:18 (-)
[agent][must-fix] Should this validation actually be removed? Test suite doesn't cover empty-input.

After the user's pass:

## path/to/file.go:43 (+)
[agent][explain] Switched to errors.Is() because the previous comparison broke wrapping.

## path/to/file.go:67-89 (+)
Pool it. Throughput matters here.

## store.go:18 (-)
Yes remove it — covered in integration_test.go:204.

## handler.go:12 (+)
Why is this exported now? Was it private before?

Reading: question on 67-89 answered, must-fix on store.go resolved with test pointer, file-level note on file.go ignored (untouched), 43 ignored (untouched), new user question on handler.go to address.

Format rules

• path is relative to repo root, case-sensitive, must match the diff
• (+) added, (-) removed, (file-level) file-wide
• Line range: :N single, :N-M span
• Body lines starting with ## need a single space prefix (revdiff reserves ## for record headers)
• Multiline bodies are fine — newlines preserved through round-trip

Intent tags

Pair [agent] with one:

• [explain] — narrate what changed and why on lines the user wouldn't otherwise understand. Pick 3–10 consequential lines, not every change.
• [question] — a real choice the user should weigh in on. Not rhetorical; only ask if you'd actually act on the answer.
• [must-fix] — agent itself is uncertain, wants confirmation.
• [nit] — minor, skippable.

One or two sentences each. TUI on a single diff line; walls of text don't fit. Longer context goes in the description file.

Don't

• Annotate every line — pick the meaningful 3–10
• Write a note without [agent] — your own note becomes user content next round
• Run revdiff in the agent's terminal — always launch into a zellij pane
• Ask the user to add a [user] prefix — protocol is one-sided
• Drop the previous round's annotations file — keep it for reference
• Reframe a [question] answer as if you knew all along. "No, do X" → "got it, switching to X."
• Relaunch to "confirm" after a clean quit

Reference

revdiff flags:

• --annotations=<file> — preload from markdown
• --description-file=<path> — info popup content (i key)
• --output=<file> — write final set on quit
• [ref] — git ref or range

zellij flags:

• --block-until-exit — block calling process until command exits or pane closes
• --close-on-exit — close pane on exit (no re-run prompt)
• <STACKED_LAYOUT_FLAGS> — placeholder, fill from zellij run --help

Full revdiff docs: https://revdiff.com/docs

[umputun]

description was deliberately scoped as metadata, not a primary review surface. That shape was settled in #130 (which proposed the same sidebar pane) when it shipped as the info popup behind i. Expanding it back into a sidebar reopens that decision.

the "virtual file" shape already exists: --stdin --stdin-name notes.md gives you a full annotation surface (markdown TOC, search, structured output) on arbitrary text. Pipe your framing into that as a separate pass and you have the same primitive without a new sidebar pane.

for the iterative aspect, --compare-old=AAA --compare-new=BBB (PR #163) plus the revdiff-planning plugin already do the rolling review for evolving documents. Pattern: agent revises content, snapshots each revision, opens revdiff with --compare-old/--compare-new --collapsed. Each round shows only what changed since last round. Zero use of --description. The diff between revisions IS the review surface. The agent contract (the marker convention) lives in the deny reason re-issued every round, not in revdiff's UI. That's how the planning loop avoids the "user keeps forgetting the protocol" problem.

your code-diff loop has a different shape than a single-document revision (multi-file diff; agent evolves both code and annotations between rounds), so revdiff-planning doesn't drop in directly. But VCS gives you the rolling delta for free: revdiff <prev-tip>..HEAD between rounds shows just last round's edits.

the protocol-in-description part is what convinces me B is wrong-shaped. That's workflow tutoring, and revdiff isn't the right place to host one workflow's onboarding. So on B: not in scope. If the agent-driven code-review skill you're prototyping turns out broadly useful, a plugin under plugins/ (in the revdiff-planning spirit) is probably the right shape, and could be considered.

[fgrehm]

Thanks for the insights. I'll do some more exploration and report back if anything changes or if I have other ideas to share.