Hunk Review

Treat Hunk as the user's interactive review UI. Never launch an interactive hunk diff or hunk show inside the agent terminal. Inspect and control an existing session through structured resources or hunk session ….

Choose the control path

1. Harness resources: When hunk:// reads are supported, prefer hunk://review?repo=…, hunk://context?repo=…, and hunk://comments?repo=…. Read hunk://review first; request raw patch content only for files that need close review.
2. Session CLI: Use hunk session list|get|review|context|navigate|reload|comment when internal resources are unavailable or mutation is required.
3. Resumable worktree UI: Use hunk resume or this repo's paired launcher to reopen the last source associated with a Git worktree.
4. Agent context file: Use --agent-context only when notes already exist as a sidecar and no live session should be steered.

Read references/live-review.md for the complete workflow and references/worktree-resume.md for paired worktree behavior.

Start with structure

hunk session list --json
hunk session get --repo . --json
hunk session review --repo . --json

Confirm session path, repo, and loaded source before commenting. Start without raw patch text. Add --include-patch only when the structured file/hunk inventory is insufficient.

If multiple sessions match, select the exact session ID. Never guess from current cwd alone when multiple worktrees or Hunk windows are open.

Review in story order

1. Inspect all changed files and hunks.
2. Identify correctness, security, data-loss, and maintainability findings.
3. Navigate the live UI to the first important location.
4. Add only findings the user would benefit from revisiting inline.
5. Batch several prepared comments in one validated operation.
6. Re-read comments and current context to verify the user-visible result.

hunk session navigate --repo . --file src/App.tsx --hunk 2
hunk session comment add --repo . --file src/App.tsx --new-line 72 --summary "Handle the rejected request"
hunk session comment list --repo . --type agent

Do not comment on every hunk. Keep summaries specific and actionable; put explanation in the comment text only when the installed Hunk version supports it.

Apply comment batches safely

Prepare a JSON file, validate it, then apply it:

python3 ~/.agents/skills/hunk-review/scripts/apply_comments.py --check comments.json
python3 ~/.agents/skills/hunk-review/scripts/apply_comments.py --repo . comments.json

The helper validates the whole payload before invoking Hunk and avoids shell-quoting failures. Hunk also validates the full stdin batch before mutation.

Reload and resume deliberately

Reload changes the source shown by an already-open window:

hunk session reload --repo . -- diff
hunk session reload --repo . -- show HEAD~1 -- README.md

Always include -- before the nested Hunk command. Prefer --repo <worktree> for normal worktree sessions. Use --session-path and --source only when intentionally repointing a live window.

hunk resume is different: it reopens the last reloadable source recorded for the current Git worktree. Use it for paired agent/review layouts and after a Hunk pane is respawned.

Verify mutations

A successful command is not enough. After adding, removing, clearing, reloading, or navigating:

• Re-read hunk://comments / hunk://context, or
• Run hunk session comment list / hunk session context.

Verify the intended file, side, and line are visible. New-line and old-line targets are not interchangeable.

Recovery

• No active sessions: If Hunk is visibly open, suspect loopback sandboxing and retry with network permission. Otherwise ask the user to open Hunk.
• Multiple matches: Pass the exact session ID.
• No visible diff file: Inspect context and loaded source; reload only if the review truly targets another source.
• Wrong worktree: Compare session Repo, session Path, and current worktree before using advanced selectors.
• Batch rejected: Fix every payload item; Hunk makes no partial mutation.
• Untracked noise: Reload diff --exclude-untracked only when the user requested tracked changes only.
• Stale CLI example: Check installed hunk --version and hunk session --help; this skill targets the deployed CLI, not unreleased main docs.

Bundled resources

• references/live-review.md — session selection, structured inspection, navigation, comments, and verification.
• references/worktree-resume.md — hunk resume, paired agent panes, and repo-specific launchers.
• scripts/apply_comments.py — validates and applies comment batches from a file.