Packaged hunk-review SKILL.md omits `session review --include-notes` and `comment clear --include-user|--all`

[shimo4228]

The packaged agent skill at skills/hunk-review/SKILL.md is the contract an agent
reads before driving a session, but it documents a stale subset of the hunk session
CLI. Two flags that exist in the shipped binary are absent from it, and both failures
are silent — the agent has no way to discover what it is missing.

Missing from SKILL.md

1. session review --include-notes

src/core/cli.ts lists it in its own usage text (and src/core/cli.test.ts covers it):

hunk session review <session-id> [--include-patch] [--include-notes]
hunk session review --repo <path> [--include-patch] [--include-notes]

SKILL.md:49 documents only:

hunk session review (--repo . | <id>) [--json] [--include-patch]

Impact: review excludes review notes by default, so an agent following SKILL.md
cannot see what the human (or a previous agent) already flagged. It then re-reports
the same finding. Nothing in the output signals that notes were withheld.

2. session comment clear --include-user / --all

Added in 0.16.0 (CHANGELOG 4bef148):

Allow session comment cleanup commands to remove human c notes: comment rm
accepts user:* note ids, and comment clear --include-user/--all clears user
notes alongside live agent comments.

SKILL.md:103 documents only:

hunk session comment clear --repo . --yes [--file README.md]

and SKILL.md:112 says comment clear accepts --file without mentioning either flag.

Impact: an agent asked to clear human notes reports that it cannot. Conversely, an
agent that learns --all elsewhere has no warning in SKILL.md that it destroys the
user's own notes.

Why this one matters more than a normal doc gap

The --type <live|all|ai|agent|user> flag from the same family did land in SKILL.md
(line 106), so the omission looks like drift rather than a deliberate exclusion.

Because the skill is shipped inside the package (Homebrew installs it under
libexec/skills/, and 0.17.0 added a home-manager option that symlinks it into
~/.claude/skills), a local fix is overwritten on the next upgrade and is invisible
to the user's own version control. The only durable place to fix it is upstream.

Suggested patch

-hunk session review (--repo . | <id>) [--json] [--include-patch]
+hunk session review (--repo . | <id>) [--json] [--include-patch] [--include-notes]

-hunk session comment clear --repo . --yes [--file README.md]
+hunk session comment clear --repo . --yes [--file README.md] [--include-user | --all]

Plus two bullets: that review omits notes unless --include-notes is passed (so
pass it before commenting), and that --include-user / --all destroy human notes
and should be confirmed with the user first.

Happy to send a PR if that is useful.

Environment

• hunk 0.17.1 (Homebrew, macOS arm64); verified against hunk session review --help
  and hunk session comment clear --help
• Confirmed still present on main as of 2026-07-25 (post-0.17.6)

[benvinegar]

I appreciate you highlighting this. I'm working on a PR that should stop this drift (mostly) going forward.