Revdiff

revdiff for pi

This skill is specific to the pi harness. Use the revdiff pi extension for interactive review sessions.

Agent usage

Call the revdiff_review tool only when the user explicitly asks for revdiff, an interactive annotation pass, or captured revdiff annotations. Do not call it for ordinary autonomous requests like "review the code", "review my changes", or "review the diff"; handle those by inspecting the code directly. Do not tell the user to run /revdiff; slash commands are user-invoked only.

When the user invokes /skill:revdiff <input>, treat <input> as a request to launch revdiff unless it is clearly a usage/configuration question or an existing-history request. First figure out the concrete reference point(s) or file target the user asked for, then call revdiff_review. Do not stop after printing the resolved ref.

Reference resolution rules:

• Accept natural language. Resolve the user's requested target to concrete revdiff args before launching.
• If the request identifies another working directory (for example in ~/source/repo), use that directory for any git/ref/path resolution, omit that directory phrase from the revdiff args, and pass the directory as the revdiff_review tool's cwd parameter.
• For natural-language commit-count requests, use two refs: prev commit, previous commit, last commit → HEAD~1 HEAD; head-3, head 3, previous 3 commits, last 3 commits → HEAD~3 HEAD.
• For tag requests, resolve the actual tag first. last tag or latest tag → run git describe --tags --abbrev=0, then pass that tag as args.
• For date requests, resolve the commit first. Examples: 2 weeks ago, yesterday, last Friday → run git rev-list -1 --before=<phrase> HEAD, then pass the resulting commit hash as args.
• For file targets, use args: "--only <path>".
• For all-files requests, map excludes explicitly. Example: all files exclude vendor and dist → args: "--all-files --exclude=vendor --exclude=dist".
• For explicit refs, ranges, flags, or two-ref requests, pass them through as revdiff args.
• If the requested natural language target cannot be resolved, say what failed and ask for a concrete ref/path. Do not guess silently.

Tool examples:

• No args: smart detection, same default target as /revdiff
• args: "main": review the current branch against main
• args: "--staged": review staged changes
• args: "--untracked": review untracked files with working-tree changes
• args: "--only README.md": review one standalone file
• args: "--all-files --exclude vendor": review all tracked files except vendor
• args: "--no-tree": review with the file tree pane hidden
• args: "--filter-unreviewed": show only files not marked reviewed
• args: "--page-overlap=2": keep 2 lines from the previous screen when paging
• args: "--start-at-change": position the cursor on the first changed line
• args: "--cross-file-motion": let cursor motion continue into adjacent files
• args: "--description='why this refactor matters' main": include review context in the info popup
• args: "--description-file=/tmp/revdiff-desc.md main": include longer markdown review context
• args: "--annotations=/tmp/revdiff-review.md main": preload in-session review notes
• args: "main", cwd: "~/source/repo": run revdiff from a specific working directory when the session was started elsewhere.
• args: "--stdin" with a unified diff piped to stdin (e.g. gh pr diff 123, git format-patch -1 --stdout, a .patch file): review a multi-file diff that lives outside the working tree — revdiff parses it as a real diff (one tree entry per file, hunk navigation, per-file annotations) instead of a context-only buffer

After revdiff_review returns annotations, address them directly from the tool result content. Do not read revdiff history after a successful captured-annotation result. Exit code 10 is success-with-annotations and is handled by the extension; do not report it as a failure. If it returns no annotations, report that no annotations were captured and stop. Do not relaunch revdiff after any no-annotation result unless the user explicitly asks for another review.

Annotation handling loop

When annotations arrive from /revdiff or revdiff_review:

1. If any revdiff_review call returns no annotations, stop. Do not relaunch revdiff after a no-annotation result unless the user explicitly asks for another review.
2. Classify each annotation into:
   • explanation requests: questions or requests to explain/clarify behavior
   • code-change directives: requested repository changes
3. Answer explanation requests first in normal chat. Do not open another revdiff session just to show the explanation.
4. If all annotations are explanation requests and no repository files change, ask the user to choose between:
   • Continue review — rerun the original revdiff_review target
   • Done with review — stop
5. Before editing repository files, list the planned file/code changes.
6. Apply code-change directives.
7. Rerun the original revdiff_review target only after repository files changed or when the user chooses to continue reviewing; preserve the original cwd parameter when one was used.
8. Add --untracked on reruns when agent-created files should be included.

User commands

• /revdiff [args] — alias for /skill:revdiff [args]; the skill resolves the request and calls revdiff_review.
• /skill:revdiff <request> — explicit skill command; same behavior as /revdiff <request>.

Recommended user command examples

/revdiff
/revdiff HEAD~1
/revdiff HEAD~1 HEAD
/revdiff main
/revdiff --staged
/revdiff --untracked
/revdiff --all-files --include src
/revdiff --all-files --exclude vendor
/revdiff --only README.md
/revdiff --no-tree
/revdiff --page-overlap=2
/revdiff --start-at-change
/revdiff --cross-file-motion
/revdiff HEAD~3 --description="why this refactor matters"
/revdiff HEAD~3 --description-file=/tmp/revdiff-desc.md
/revdiff main --annotations=/tmp/revdiff-review.md
gh pr diff 123 | revdiff --stdin
git format-patch -1 --stdout | revdiff --stdin