version: "1.0.0" name: wiff-review description: Read and annotate a wiff code-review session from the command line. Use when asked to review a diff and leave comments in wiff, or to read and address the comments already left in a wiff review.

Wiff Review

wiff is a terminal-first code-review tool. A review lives in a local session that a human browses in the wiff TUI while an agent reads and writes the same session through the wiff command line. The TUI belongs to the human: never launch or drive it. Do all of your work through the wiff subcommands below.

If there is no session to act on, ask the user to start one with wiff first. The exception is when you are the automation that opens reviews (see below).

Opening or refreshing a review from automation

When your job is to trigger reviews rather than review within a session a human opened, create-or-refresh the session for the current changes in one idempotent step:

wiff new --no-tui --if-needed

It creates a session when none exists for these changes, refreshes one in place when the working copy has moved on, and does nothing when it is already current. With no changes and no session yet, it exits non-zero with "no changes to review". By default it reviews the uncommitted working-tree changes; add --from-base to review the whole branch against its trunk instead. Requires --no-tui.

Selecting the session

Every command acts on the active session for the current project by default, so run wiff from inside the checkout being reviewed and you can usually omit any session flag. When the active session is not the one you want, or the project cannot be derived from the working directory, select it explicitly:

wiff session list
wiff render --session 2br8zf30h
wiff comment add --agent --session 2br8zf30h --review --body "..."

• wiff session list prints the sessions for this project and their ids.
• --session <id> targets a specific session instead of the active one.
• --project <name> forces the project when the working directory cannot name

it on its own.

Exploring existing code

Not every review is about a change. To annotate existing code, open an explore review: an empty session over the current working copy, to which you add the files you want to comment on.

wiff new --no-tui --explore
wiff explore add src/lib.rs src/parser.rs

• wiff new --explore creates the review with no files yet. Add --no-tui when

you are driving it from the command line rather than handing it to a human.

• wiff explore add <PATH>... brings files into the review, each captured at its

current state. Re-adding a file already under review does nothing.

• You do not have to add a file before commenting on it: `wiff comment add --file

F ... on an explore review adds F first when it is not yet present, so --file` doubles as the way to bring a file in.

Everything else, reading with wiff render and leaving or revising comments, works the same as on a diff review.

Reading a review

Start here when asked to read a review or to address the comments it holds.

wiff render
wiff render --format json
wiff comment list

• wiff render prints the review as markdown: comments grouped by file, each

led by its number (like #3) and showing its author and kind, target location, resolved or outdated state, body, and a fenced snippet of the surrounding code. This is the one command you need to read the review and to pick up the numbers you act on below.

• Each comment has a short review-scoped number, shown as #N, and a long ULID.

Every command that names a comment (resolve, verdict, rm, --reply-to) accepts either. Prefer the number: pass it as the bare digits N (a leading # starts a comment in the shell, so write 3, not #3, unless you quote it as '#3'). The ULID stays valid and is the durable identity across sessions.

• When the review has a description (a title and optional body, the same shape

as a commit message), wiff render prints it under a ## Description heading and the JSON includes it in a top-level description field. See below to set one.

• wiff render --format json prints the same folded state as JSON for

programmatic use. Each comment reports updated_seq and updated_at. To order changes or find the most recent one, use updated_seq, which always advances; updated_at is a display timestamp and, for a comment imported from a forge, can predate an earlier change.

• wiff comment list is an optional compact form: one comment per line, number

first, with its status and location, when you want a terse pass without the bodies and snippets.

When you finish addressing a comment, resolve it so the human sees it is done. Pass --agent here too, so the resolution is attributed to you rather than the human:

wiff comment resolve --agent 7

Leaving review comments

Use these when asked to review a change and record your findings. Always pass --agent on every command that writes to the review, so your comments, resolutions, and withdrawals are attributed to you rather than the human.

wiff comment add --agent --file src/lib.rs --line 42 --body "This can overflow."
wiff comment add --agent --file src/lib.rs --line 10-14 --body "Extract this loop."
wiff comment add --agent --file src/lib.rs --line 42 --side before --body "..."
wiff comment add --agent --file src/lib.rs --body "This module needs tests."
wiff comment add --agent --review --body "Overall the change reads well."
wiff comment add --agent --reply-to 3 --body "Agreed, done."

• --file F --line N comments on a single line; --line N-M on an inclusive

range. Line numbers are 1-based.

• --reply-to <comment> replies to an existing comment, named by its number or

ULID, forming a thread. A reply takes its position from the comment it answers, so it needs no file or line. A thread shows as a flat sequence in the order the replies were written; a reply to a withdrawn comment is refused.

• --side after (the default) refers to the post-change content; `--side

before` refers to the pre-change content.

• --file F with no --line comments on the whole file; --review comments on

the change overall.

• --verdict approve or --verdict request_changes records a verdict along

with the comment. A comment without one is a neutral remark.

• Provide the body with --body, or pipe it on stdin for anything long or

multi-line:

printf '%s\n' 'First point.' 'Second point.' | wiff comment add --agent --file src/lib.rs --line 42

To revise your own comments:

wiff comment list
wiff comment resolve --agent 3
wiff comment resolve --agent --reopen 3
wiff comment verdict --agent 3 request_changes
wiff comment edit --agent 3 --body "Revised wording."
wiff comment rm --agent 3

• wiff comment resolve <comment> marks a comment resolved; --reopen undoes

that. Name the comment by its number or ULID, as everywhere.

• wiff comment verdict <comment> approve|request_changes|none sets or clears

the verdict on your own comment. Only its author may. wiff render reports each actor's current verdict, reduced from their comments, under a ## Verdicts heading and in a top-level verdicts field in the JSON.

• wiff comment edit <comment> rewrites a comment's body from --body or

stdin. You may edit only your own comments.

• wiff comment rm <comment> withdraws a comment. You may withdraw only your

own comments.

Describing the review

A review can carry a description: a one-line title and an optional body, the same shape as a commit message. It is the review's own summary, distinct from any comment.

wiff description show
wiff description set --agent "Tidy the parser"
printf '%s\n\n%s\n' 'Tidy the parser' 'Split the lexer out.' | wiff description set --agent

• wiff description show prints the current description.
• wiff description set sets it from the argument, or from piped stdin when no

argument is given. The first line is the title; the rest, past a blank line, is the body. Setting it again replaces the previous description.

• Pass --agent so the description is attributed to you rather than the human.

Guidelines

• Read the change before commenting. wiff render gives you each comment with

its surrounding code; read the diff itself from the checkout as needed.

• Comment where it matters: intent, correctness, risks, and follow-ups. Do not

leave a note on every hunk; highlight what the human would not spot alone.

• Anchor each comment on the most specific target you can, a line or a range,

and fall back to a whole-file or review comment only for points that have no single home.

• Quote comment bodies in the shell so punctuation is not mangled, or pipe them

on stdin.