revdiff

revdiff - TUI 差分レビュー

ターミナルオーバーレイで revdiff TUI を使用し、インライン注釈を付けながら差分をレビューします。git、hg、jj のリポジトリに対応しており、自動検出します。

スクリプトパスの解決

利用可能なスキルのカタログにある、このスキルの絶対パスから <plugin-root> を解決します。これは、このプラグインの .codex-plugin/plugin.json を含むディレクトリです。次に、以下を設定します。

SCRIPT_DIR="<plugin-root>/skills/revdiff/scripts"

コマンドを実行する前に、<plugin-root> を解決済みの絶対パスに置き換えてください。このスキル全体では、スクリプトパスの代わりに $SCRIPT_DIR を使用します。

注：ランチャーのオーバーライドチェーン（ユーザー設定の ${CLAUDE_PLUGIN_DATA} → 同梱版）は Claude 専用です。Codex ユーザーは、ローカルのマーケットプレイスチェックアウトでランチャーをカスタマイズし、プラグインを再インストールできます。

起動のトリガー

• "revdiff"、"review diff"、"review changes"、"annotate diff"
• "revdiff HEAD~1"、"revdiff main"
• "hg review with revdiff"、"review jj change"
• "revdiff all files"、"review all files"、"browse all files"
• "revdiff all files exclude vendor"
• "revdiff README.md"、"revdiff docs/plan.md"、"revdiff /tmp/notes.txt" — 単一ファイルのレビュー（--only モード）
• "review this file"、"annotate this file"、"review file with revdiff"
• "open this review in revdiff"、"show review in revdiff"、"review in revdiff" — セッション内レビューを開く（事前読み込みモード）

質問への回答

ユーザーがレビューセッションを依頼するのではなく、revdiff の設定、テーマ、キー割り当て、インストール、使い方について質問した場合は、references/ 内のリファレンスファイルを参照して、直接回答してください。情報を求める質問に対して TUI を起動してはいけません。

• references/install.md — インストール方法とプラグインのセットアップ
• references/config.md — 設定ファイル、オプション、色、chroma テーマ
• references/usage.md — 使用例、キー割り当て、出力形式

既存のレビュー履歴の利用

ユーザーが「レビューを探して」「最新の revdiff 注釈を使って」「別のターミナルで今行ったレビューを表示して」「以前何に注釈を付けたか教えて」のように言った場合、ユーザーはこのプラグインのフロー外で revdiff を実行し、保存された注釈を Codex に処理させようとしています。ヘルパースクリプトを使って永続履歴ディレクトリから最新のファイルを読み込み、新しいランチャー呼び出しで取得した注釈と同様に、Step 3.5 の分類を通じて処理してください。

$SCRIPT_DIR/read-latest-history.sh

このスクリプトは $REVDIFF_HISTORY_DIR（デフォルトは ~/.config/revdiff/history）から履歴ディレクトリを解決し、VCS ルートのベース名（jj/git/hg）を使ってリポジトリのサブディレクトリを特定し、path: ヘッダーに現在のチェックアウトを示す最新の .md ファイルを出力します（ディレクトリのヘッダーはリポジトリのルートと一致する必要があります。git との照合がない単一ファイルの --only ヘッダーの場合、そのファイルがルート直下にある必要があります）。各履歴ファイルには、ヘッダー（path、refs、利用可能な場合は git のコミットハッシュ）、## file:line (type) 形式の注釈、注釈対象ファイルの未加工の git 差分が含まれます。commit: 行と差分ブロックは git からのみ取得されます。hg/jj リポジトリでは差分ブロックは空になり、コミットハッシュは記録されません。ディレクトリ構成、stdin/only の処理、オーバーライドのオプションについては、references/usage.md の「Review History」セクションを参照してください。

レビューが接続切断で中断された場合も、履歴ファイルから復旧できます。シグナルによる終了時（SSH/tmux クライアント切断による SIGHUP、または SIGTERM）に、revdiff は現在の注釈を履歴に保存します。-o の出力は保存されません。そのため、read-latest-history.sh で引き続き注釈を復元できます。

セッション内レビューを開く

ユーザーがセッション内レビューを revdiff で開くよう求めた場合（会話に、セッション中に以前作成したレビューコメントがすでに含まれている場合）、references/usage.md の「Output Format」セクションに記載された形式でそれらのコメントを一時ファイル（例：/tmp/revdiff-review-XXXXXX.md）に書き込み、通常のランチャーフロー（Step 1 の ref 検出、Step 2 の呼び出し）を実行して、--annotations=<temp-path> を追加します。Step 3 以降では、選別済みの注釈を通常どおり処理します。

ワーキングツリーの外にある差分をレビューする

レビュー対象が現在のリポジトリの状態ではない場合があります。たとえば、GitHub PR の差分、ディスク上のパッチファイル、または git format-patch -1 --stdout の出力などです。統合差分を revdiff --stdin にパイプすると、入力はコンテキストのみのバッファーではなく、実際の複数ファイルの差分として解析されます（ファイルごとにツリーエントリーが作成され、ハンクを移動でき、ファイルごとに注釈を付けられます）。revdiff は統合差分のシグネチャを自動検出します。不正なパッチの場合、入力は通知なしで生テキストモードにフォールバックします。

次の場合は、通常の起動フローの代わりにこれを使用してください。

• ユーザーが「PR #N をレビューして」「このパッチをレビューして」「gh pr diff の出力をレビューして」と依頼した場合、またはパッチの URL／パスを提示した場合
• 差分がローカルでチェックアウトされていないコミットを示している場合（例：リモートのみの PR にある他者のブランチ）
• ユーザーが統合差分を貼り付け、ワーキングツリーではなく、その差分のレビューを依頼した場合

実行例（通常のフローと同じランチャーを経由します）。

gh pr diff 123 | $SCRIPT_DIR/launch-revdiff.sh --stdin
git format-patch -1 --stdout | $SCRIPT_DIR/launch-revdiff.sh --stdin
cat /tmp/feature.patch | $SCRIPT_DIR/launch-revdiff.sh --stdin

--stdin は refs、--staged、--only、--all-files、--include、--exclude、--annotations と併用できません。そのため、Step 1 の ref 検出とは組み合わせず、ランチャーから戻ったら直接 Step 3 に進んでください。注釈は --stdin-name ではなく、差分に記載された実際のファイルパスをキーとして返されます。

仕組み

1. ターミナルオーバーレイ（agterm の全画面オーバーレイ、tmux ポップアップ、Zellij のフローティングペイン、herdr タブ、kitty オーバーレイ、wezterm／Kaku の分割ペイン、cmux 分割、ghostty の分割＋ズーム、iTerm2 の分割ペイン、または Emacs vterm フレーム）で revdiff を起動します
2. ユーザーが差分を移動し、特定の行に注釈を追加します
3. 終了時に、注釈が stdout から取得されます
4. Codex が注釈を読み取り、それぞれに対応します
5. ループ：修正を検証するために revdiff を再起動し、ユーザーはさらに注釈を追加できます
6. ユーザーが注釈を付けずに終了した場合、注釈が取得されなかったことを報告し、レビューのワークフローを停止します

ワークフロー

ステップ 1：レビュー モードを決定する

全ファイルモード：$ARGUMENTS が「all files」「all-files」または「browse all files」に一致する場合（「exclude 」部分は任意）、全ファイルモードを使用します。

• ランチャーに --all-files を渡します
• ユーザーが除外パターン（例：「exclude vendor」「exclude vendor and mocks」）を指定した場合、それぞれを --exclude=<prefix> として渡します
• ref の検出は完全にスキップし、ステップ 2 に進みます
• 例：「all files exclude vendor」→ --all-files --exclude=vendor

ファイルレビュー モード：$ARGUMENTS がディスク上のファイルを指す単一のトークン（例：docs/plans/feature.md、/tmp/notes.txt、README.md、main.go、file.blah）の場合、ファイルレビューとして扱います。

• test -f "$ARGUMENTS" で判定します。ファイルが存在する場合は、ファイルレビュー モードです
• また、トークンが / または ./ で始まる場合、あるいは / を含み拡張子がある場合（例：src/app.go）は、現在のディレクトリからまだアクセスできない場合でも、ファイルレビューとして扱います
• ref の検出は完全にスキップします
• --only=<filepath> を指定してステップ 2 に進みます（ref 引数なし）
• VCS リポジトリの内外どちらでも動作します。revdiff はファイルをコンテキスト専用としてディスクから読み取ります
• あいまいなトークン（例：main — ブランチ名である可能性と、拡張子のないファイル名である可能性がある場合）では、ref モードを優先します。test -f でも git rev-parse --verify でも解決できない場合に限り、ユーザーに確認します

ref モード：$ARGUMENTS に明示的な ref（例：HEAD~1、main、または 2 つの ref による差分を表す main feature）が含まれる場合は、そのまま使用します。

自動検出：ref が指定されていない場合は、スマート検出スクリプトを実行します。

$SCRIPT_DIR/detect-ref.sh

スクリプトは、次の構造化フィールドを出力します。

• branch、main_branch、is_main、has_uncommitted、has_staged_only
• suggested_ref — revdiff に渡す ref（空の場合は未コミットの変更）
• use_staged — true の場合、ランチャーに --staged を渡します（ステージ済みの変更のみが検出された状態）
• needs_ask — true の場合、続行する前にユーザーに確認します

use_staged: true の場合、ランチャーに --staged を渡します。これは、すべての変更がインデックスにあり（ステージ済み）、ステージされていない変更がないことを意味します。--staged を指定しないと、revdiff は空の差分を表示します。

needs_ask: true の場合（未コミットの変更があるフィーチャーブランチの場合）、選択肢を番号付きリストでユーザーに提示し、回答を待ちます。

1. 未コミットの変更のみ — ref を渡しません（作業中の変更のみをレビューします）
2. ブランチと {main_branch} の比較 — main_branch を ref として渡します（未コミットの変更を含むブランチ全体の差分）

needs_ask: false の場合、suggested_ref をそのまま使用します。

• main ＋未コミットの変更 → ref なし（未コミットの変更）
• main ＋ステージ済みの変更のみ → ref なし＋--staged（ステージ済みの変更）
• main ＋クリーン → HEAD~1（直近のコミット）
• フィーチャーブランチ＋クリーン → main ブランチ名（ブランチ全体の差分）

ステップ 2：レビューの起動

ユーザーのために revdiff を起動する場合（リファクタリングや分析の直後など）、--description="..." を渡して、情報ポップアップ（i キー）で変更内容と確認すべき点を説明してください。Markdown を使用できます。長めの文章の場合は、Markdown を一時ファイルに書き込み、--description-file=/tmp/revdiff-desc-XXXXXX.md を渡してください。この 2 つのフラグは同時に使用できません。どちらも省略可能です。追加すべき有用なコンテキストがない場合は省略してください。

最近の変更で新しい未追跡ファイルが作成された可能性が高い場合（新しいパッケージ、新しいテストファイル、新しいドキュメント、まだ git add されていない新しいスクリプトなど）は、--untracked を渡して、それらのファイルをツリーに表示してください。作業ツリーモード（ref なし、--staged なし）で使用します。未追跡ファイルは履歴上の差分に含まれないため、ref 同士のレビューでは省略してください。

--start-at-change は、ユーザーがそのカーソル設定を明示的に求めた場合にのみ渡してください。自動的に推測してはいけません。

--filter-unreviewed は、未レビューとしてマークされたファイルだけにツリーを絞り込むようユーザーが求めた場合にのみ渡してください。自動的に推測してはいけません。レビュー中に F キーを押すと、同じフィルターを切り替えられます。

--cross-file-motion は、カーソル移動が隣接ファイルにも続くようユーザーが明示的に求めた場合にのみ渡してください。自動的に推測してはいけません。

--stop-at-annotations は、ハンク外のアノテーションでも [ と ] で停止するようユーザーが明示的に求めた場合にのみ渡してください。自動的に推測してはいけません。

ランチャースクリプトを実行します。

$SCRIPT_DIR/launch-revdiff.sh [base] [against] [--staged] [--untracked] [--filter-unreviewed] [--cross-file-motion] [--stop-at-annotations] [--only=file1] [--all-files] [--exclude=prefix] [--description=text|--description-file=path]

重要 — 長時間実行されるコマンド：ランチャーは、ユーザーが TUI オーバーレイでレビューを終えるまで処理をブロックします。デフォルトの bash ツールのタイムアウトを超えることがあります。bash のタイムアウトパラメーターは、ハーネスで許可されている最大値（例：1800000 以上）に設定してください。この処理に run_in_background を使用してはいけません。バックグラウンドタスクの処理は、対話型 TUI ランチャーでは信頼性がありません。レビューがタイムアウトの上限を超えた場合は、ステップ 3 のフォールバックで対応します。

切断に強い tmux ウィンドウモード：tmux 内で実行する場合は、ランチャーの前に REVDIFF_TMUX_WINDOW=1 を付けると、クライアント所有の display-popup ではなく、サーバー所有の永続的な tmux ウィンドウで revdiff を開けます。SSH 接続や tmux クライアントが切断されてもレビューは保持されるため、再接続すればそのまま続けられます。これはランチャーの環境変数であり、revdiff のフラグではありません。

ペインスコープのオーバーレイ（herdr）：herdr 内で実行する場合は、REVDIFF_HERDR_PANE=1 を設定すると、新しい全画面タブではなく、エージェント自身のペインを拡大分割して revdiff を開き、エージェントのペインに 1 キー操作で戻れるようにします。ユーザーが環境変数として設定します。古い herdr CLI ではタブオーバーレイにフォールバックします。これはランチャーの環境変数であり、revdiff のフラグではありません。

ペインスコープのオーバーレイ（agterm）：agterm の分割ペイン内で実行する場合は、REVDIFF_AGTERM_PANE=1 を設定すると、セッション全体ではなくエージェント自身のペイン内で revdiff を開き、隣のペインを表示したままにできます。ユーザーが環境変数として設定します。分割ペインの外では無視されます。これはランチャーの環境変数であり、revdiff のフラグではありません。

フローティングパネル（agterm）：REVDIFF_AGTERM_SIZE_PERCENT=N（1～100）を設定すると、セッション全体の agterm オーバーレイを、セッションに対して N パーセントのサイズのフローティングパネルとして開き、レビュー中もエージェントとのチャットを周囲に表示できます。ユーザーが環境変数として設定します。ペインスコープのオーバーレイでは無視されます。これはランチャーの環境変数であり、revdiff のフラグではありません。

スクリプトの処理：

• 利用可能なターミナルを検出します（agterm → tmux → Zellij → herdr → kitty → wezterm/Kaku → cmux → ghostty → iTerm2 → Emacs vterm）
• オーバーレイ内で revdiff を起動します
• アノテーションの出力を一時ファイルに記録します
• 記録したアノテーションを標準出力に表示します

同梱のランチャーは REVDIFF_EXIT_CODE_ON_ANNOTATIONS を設定します。終了コード 10 はアノテーションが記録されたことを示し、ランチャーの失敗ではありません。それ以外のゼロ以外の終了ステータスは失敗として扱ってください。こうした失敗の場合、ランチャーは revdiff 自体の stderr をそのまま中継します。どの引数に問題があったか推測せず、そのテキストを一字一句そのまま報告してください。

Agterm セッションと承認エスカレーション

Codex が agterm セッション内で実行されると、ランチャーは agterm ネイティブの全ペインオーバーレイで revdiff を開きます。これは tmux より先に確認される第一候補のバックエンドです。この分岐には、ランチャーの環境に AGTERM_SESSION_ID と AGTERM_SOCKET が必要です。

承認またはエスカレーションが必要な Codex コマンドは、新しい環境で実行されます。この環境では PATH のみを残し、TERM_PROGRAM と GHOSTTY_* に加えて、すべての AGTERM_* 変数が削除されます。これらの変数がない状態で起動すると、ランチャーは agterm 分岐をスキップし、no overlay terminal available で失敗します。

エスカレーションの前に、通常（エスカレーションされていない）環境で値を読み取り、承認済みコマンドにリテラル値として埋め込んでください。

AGTERM_SESSION_ID='<captured-id>' \
AGTERM_SOCKET='<captured-socket>' \
$SCRIPT_DIR/launch-revdiff.sh --only=<file>

• 承認済みコマンド内で $AGTERM_SESSION_ID ／ $AGTERM_SOCKET を参照しないでください。これらはすでに未設定のため、展開結果は空になります。まず通常環境で読み取り、その後、リテラル文字列を貼り付けてください。
• セッション ID がない場合に、active セッション（agterm のデフォルト）を指定して回避しないでください。revdiff が別の agterm ウィンドウやセッションで開く可能性があります。取得したセッション ID を使うことで、オーバーレイをレビュー中のセッションに表示できます。

ステップ 3：注釈を処理する

ランチャーの出力を収集する：通常、ランチャーは標準出力に注釈を付けて同期的に戻ります。以下の説明に従って処理してください。bash ツールが終了コード 10 を報告した場合は、標準出力を読み、注釈として処理してください。失敗として扱わないでください。bash ツールがタイムアウトを報告した場合は、ランチャープロセスだけが終了していますが、revdiff 自体はオーバーレイ内で開いたままで、注釈も失われていません。revdiff はユーザーが終了した時点で注釈をディスクに書き込み、O を押せばいつでもフラッシュできます。ランチャーを再試行しないでください。代わりに、次の手順に従ってください。

1. ユーザーを安心させ、どちらの方法も選べることを伝え、何も失われていないことを明確にしてください。短くまとめ、保存の仕組み（ディスクへの書き込み、O によるフラッシュ、終了時の保存）は説明しないでください。ユーザーに説明する必要はありません。たとえば、次のように伝えてください。「revdiff のレビューを待機していたプロセスがタイムアウトして終了しましたが、問題ありません。付けた注釈は安全に残っています。準備ができたら、注釈を読み込んで続けるか、終了して停止するか、どちらにするかメッセージで教えてください。」注釈を読み込みたいと決めつけないでください。注釈を付けずに終了することも、停止を選ぶことも、有効な選択肢です。
2. ユーザーからの返信を待ちます。オーバーレイがフォーカスされている間は返信できないため、返信があった場合はセッションに戻ってきたことを意味します（終了したか、O でフラッシュして切り替えたかのどちらかです）。
3. 返信があったら、必ず対応してください。手順 1 で止めてはいけません。停止を選んだ場合は、その意向を確認して終了します。それ以外の場合は、保存された注釈を読み込みます。最も新しい出力ファイルから読み込んでください（ランチャーは $TMPDIR が設定されていればその場所に、設定されていなければ /tmp に書き込みます）。

   output_file="$(find -H "${TMPDIR:-/tmp}" -maxdepth 1 -type f -name 'revdiff-output-*' -user "$(id -u)" -mmin -120 -exec ls -t {} + 2>/dev/null | head -1)"
   if [ -n "$output_file" ] && [ -f "$output_file" ]; then
     cat "$output_file"
   fi
   

4. 出力ファイルに内容があれば、以下の説明に従って注釈として処理します。空または存在しない場合は、永続的なレビューヒストリーを参照してください。ランチャーのクリーンアップで一時ファイルが削除されても、レビューヒストリーは残ります。$SCRIPT_DIR/read-latest-history.sh を実行し、「既存のレビューヒストリーの利用」を参照して、その ## Annotations セクションの注釈を処理してください。両方とも空の場合に限り、ユーザーは注釈を付けずに終了したと判断します。

どちらの読み込みも完全な内容を返します。revdiff は終了時に出力ファイルをアトミックに書き込み、プロセスが終了する前にヒストリーの項目全体が記録されます。そのため、途中までの内容を読み取ることはありません。ただし、そのファイルが今回のレビューのものだとは限りません。検索対象はユーザー自身のファイルに限られ、2 時間より古いファイルは除外されますが、最近の残存ファイルや、同じ $TMPDIR 内で行っているユーザー自身の別のレビューが、最も新しい一致になる場合があります。

レビュアーは、意図的に revdiff を開いたままにして O を押し、終了せずにセッション中の注釈を同じ出力ファイルへフラッシュすることもできます。フラッシュには同じアトミック書き込みが使われるため、上記の代替手順による読み込みでも完全なファイルが返されます。オーバーレイを開いたまま「メモをフラッシュしました。続けてください」のようにユーザーが伝えてきた場合は、タイムアウト時の代替手順と同じ方法で最も新しい出力ファイルを読み、注釈を処理してください。revdiff を再起動してはいけません。コードの変更が終わったら、レビュアーは R で再読み込みし、同じセッションで続けます。このためにランチャーのフラグを変更する必要はありません。ランチャーはすでに出力ファイルを渡しており、O はそのファイルを再利用します。

スクリプトが出力を生成した場合、ユーザーは注釈を付けています。出力形式は次のとおりです。

## file.go:43 (+)
use errors.Is() instead of direct comparison

## store.go:18 (-)
don't remove this validation

各注釈ブロックには、次の内容が含まれます。

• ## filename:line (type) — ファイルと行を示します。（(+) = 追加、(-) = 削除、(file-level) = ファイル全体へのメモ）
• その下のコメントテキスト — ユーザーが変更してほしい内容

ステップ 3.5：注釈を分類する

注釈を次の 2 つのカテゴリに分けます。

説明のリクエスト — 注釈が次のいずれかのルールに一致するもの（大文字と小文字を区別しません）：

• テキスト内のどこかに連続する疑問符が 2 つ以上含まれる（??、??? など） — 「説明してください」を意味する、言語に依存しない簡易表現です
• または、次のいずれかで始まるもの：explain、remind、describe、what is、what are、how does、how do、clarify

これらはユーザーが回答を求めている質問であり、コード変更ではありません。

コード変更の指示 — 上記以外のすべて。コードを変更する指示です。

説明のリクエストが見つかった場合：

1. 各説明のリクエストに回答します — 参照されているコードを読み、わかりやすい Markdown の説明を生成します

2. 同じバッチにコード変更の指示も含まれている場合は、保留中として記録します（説明ループの後、ステップ 4 に進む際に引き継がれます）

3. 説明ループに入ります。

   a. 説明を一時的な Markdown ファイルに書き込みます（例：/tmp/revdiff-explain-XXXXXX.md） b. ランチャースクリプト経由で --only=/tmp/revdiff-explain-XXXXXX.md を指定して revdiff を起動します。これにより、目次サイドバー付きのスクロール可能な Markdown ビューとして説明が開きます c. ユーザーが注釈を付けずに終了した場合 → 説明が承認されたものとして、一時ファイルを削除し、次に進みます。

   • 保留中のコード変更の指示がある場合 → ステップ 4 に進みます
   • それ以外の場合 → ステップ 6 に進みます（元の diff ref を指定して revdiff を再起動します） d. ユーザーが説明に注釈を付けた場合 → それらは追加の質問や説明のリクエストです。注釈を読み、説明の Markdown を修正または拡充し、更新した一時ファイルを書き込んで、手順 (b) に戻ります

ユーザーが注釈を付けずに終了するまで、説明ループを続けます。これにより、説明の特定の部分について、ユーザーが詳細や訂正を求めながら自然にやり取りできます。

説明のリクエストがない場合 — すべての注釈がコード変更の指示です。ステップ 4 に直接進みます。

ステップ 4：変更を計画する

コード変更の注釈を分析した計画を Markdown のリストとして記述します。

• 各注釈をファイルと行の参照とともに列挙します
• それぞれに対して、予定している変更を説明します
• ユーザーに「これらの変更を進めてもよいですか？」と尋ねます

コードを変更する前に、ユーザーの確認を待ちます。

ステップ 5：注釈に対応する

ユーザーが計画を承認した後、実際のソースコードを修正します。各注釈は指示として扱います。

ステップ 6：ループ

修正後（またはステップ 3.5 から「レビューを続ける」を選んだ後）、同じ ref を指定してランチャースクリプトを再度実行します。ユーザーは次の操作を行えます。

• さらに注釈を追加する → ステップ 3 に戻ります
• 注釈を付けずに終了する → 注釈は取得されていません（出力なし）。ステップ 7 に進みます

ステップ 7：完了

スクリプトが出力を生成しない場合、注釈は取得されていません。ユーザーにそのことを伝え、レビューワークフローを終了します。この結果だけでは、それ以上の変更は許可されません。以前に明示されたユーザーの指示は引き続き有効です。

セッションの例

User: "revdiff HEAD~1"
→ launch revdiff in tmux popup with HEAD~1 diff
→ user annotates: "handler.go:43 - use errors.Is()"
→ user quits
→ annotations captured
→ plan changes: "add errors.Is() check at handler.go:43"
→ user approves
→ fix applied
→ re-launch revdiff HEAD~1
→ user sees fix, quits without annotations
→ "No annotations were captured."

User: "revdiff HEAD~3"
→ launch revdiff in tmux popup with HEAD~3 diff
→ user annotates: "server.go:72 - explain what this mutex protects"
→ user quits
→ annotation classified as explanation request (starts with "explain")
→ Codex reads server.go:72, generates markdown explanation
→ writes to /tmp/revdiff-explain-XXXXXX.md
→ launch revdiff --only=/tmp/revdiff-explain-XXXXXX.md (explanation view with TOC)
→ user reads explanation, annotates: "what about the race condition on line 80?"
→ Codex refines explanation, rewrites temp file
→ re-launch revdiff --only=/tmp/revdiff-explain-XXXXXX.md
→ user reads updated explanation, quits without annotations
→ explanation accepted, clean up temp file
→ re-launch revdiff HEAD~3 (back to diff review)
→ user quits without annotations
→ "No annotations were captured."

User: "revdiff all files exclude vendor"
→ launch revdiff with --all-files --exclude=vendor
→ user browses all tracked files, annotates as needed
→ same annotation loop as above

User: "revdiff docs/plans/feature.md"
→ test -f docs/plans/feature.md succeeds → file review mode
→ launch revdiff with --only=docs/plans/feature.md (context-only view, no ref)
→ user annotates prose: "section 'Open questions':3 - drop this, resolved"
→ user quits
→ same annotation loop as above (applies to the file content)