Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

fix: make PR reviewer post actionable feedback, not explanations (#1145)

Maximilian Roos485177daff57
diff --git a/.claude/skills/pr-review/SKILL.md b/.claude/skills/pr-review/SKILL.md
index 9b9536c62..4e1fcc1e9 100644
--- a/.claude/skills/pr-review/SKILL.md
+++ b/.claude/skills/pr-review/SKILL.md
@@ -25,56 +25,54 @@ REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
BOT_LOGIN=$(gh api user --jq '.login')
HEAD_SHA=$(gh pr view <number> --json commits --jq '.commits[-1].oid')
-# Check if bot already approved this exact revision
-APPROVED_SHA=$(gh pr view <number> --json reviews \
- --jq "[.reviews[] | select(.state == \"APPROVED\" and .author.login == \"$BOT_LOGIN\") | .commit.oid] | last")
-
-# Check if bot already commented on this exact revision (e.g., on self-authored
-# PRs where the bot cannot approve)
-COMMENTED_SHA=$(gh pr view <number> --json reviews \
- --jq "[.reviews[] | select(.state == \"COMMENTED\" and .author.login == \"$BOT_LOGIN\") | .commit.oid] | last")
-```
-If `APPROVED_SHA == HEAD_SHA`, exit silently — this revision is already approved.
+# Find the bot's most recent substantive review (any state)
+LAST_REVIEW_SHA=$(gh pr view <number> --json reviews \
+ --jq "[.reviews[] | select(.author.login == \"$BOT_LOGIN\" and .body != \"\")] | last | .commit.oid // empty")
+```
-If `COMMENTED_SHA == HEAD_SHA`, exit silently — this revision has already been
-reviewed (the bot likely cannot approve because it authored the PR).
+If `LAST_REVIEW_SHA == HEAD_SHA`, this commit has already been reviewed — exit
+silently. The only exception: a conversation comment asks the bot a question
+(checked below).
-If the bot reviewed a previous revision (`APPROVED_SHA` or `COMMENTED_SHA`
-exists but differs from `HEAD_SHA`), check the incremental changes since the
-last review:
+If the bot reviewed a previous commit (`LAST_REVIEW_SHA` exists but differs from
+`HEAD_SHA`), check the incremental changes:
```bash
REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
-LAST_REVIEWED_SHA="${APPROVED_SHA:-$COMMENTED_SHA}"
-gh api "repos/$REPO/compare/$LAST_REVIEWED_SHA...$HEAD_SHA" \
+gh api "repos/$REPO/compare/$LAST_REVIEW_SHA...$HEAD_SHA" \
--jq '{total: ([.files[] | .additions + .deletions] | add), files: [.files[] | "\(.filename)\t+\(.additions)/-\(.deletions)"]}'
```
-If the new changes are trivial, skip the full review (steps 2-3) and do not
-re-approve — the existing approval stands. Still proceed to step 5 to resolve
-any bot threads that the trivial changes addressed, then exit. Rough heuristic:
-changes under ~20 added+deleted lines that don't introduce new functions, types,
-or control flow are typically trivial (review feedback addressed, CI/formatting
-fixes, small corrections). Only proceed with a full review and potential
-re-approval for non-trivial changes (new logic, architectural changes,
-significant additions).
+If the incremental changes are trivial, skip the full review (steps 2-3) — the
+existing review stands. Still proceed to step 5 to resolve any bot threads
+addressed by the new changes, then exit. Rough heuristic: changes under ~20
+added+deleted lines that don't introduce new functions, types, or control flow
+are typically trivial (review feedback addressed, CI/formatting fixes, small
+corrections). Only proceed with a full review for non-trivial changes.
-Then check existing review comments and conversation to avoid repeating prior
-feedback and to catch questions directed at the bot:
+Then read all previous bot feedback and conversation:
```bash
REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
BOT_LOGIN=$(gh api user --jq '.login')
-gh api "repos/$REPO/pulls/<number>/comments" --paginate --jq '.[].body'
-gh api "repos/$REPO/pulls/<number>/reviews" --jq '.[] | select(.body != "") | .body'
+# Previous review bodies
+gh api "repos/$REPO/pulls/<number>/reviews" \
+ --jq ".[] | select(.user.login == \"$BOT_LOGIN\" and .body != \"\") | {state, body}"
+# Inline review comments
+gh api "repos/$REPO/pulls/<number>/comments" --paginate \
+ --jq ".[] | select(.user.login == \"$BOT_LOGIN\") | {path, line, body}"
+# Conversation (catch questions directed at the bot)
gh api "repos/$REPO/issues/<number>/comments" --paginate \
--jq '.[] | {author: .user.login, body: .body}'
```
-If any conversation comment asks the bot a question (mentions `$BOT_LOGIN`,
-replies to a bot comment, or asks a question clearly directed at the reviewer),
-respond in the review body rather than silently approving.
+**Do not repeat any point from previous reviews.** If a previous review already
+noted an issue, don't raise it again.
+
+If a conversation comment asks the bot a question (mentions `$BOT_LOGIN`,
+replies to a bot comment, or is clearly directed at the reviewer), address it in
+the review body.
### 2. Read and understand the change
@@ -151,6 +149,59 @@ If the same issue exists elsewhere, flag it in the review.
### 4. Submit
+#### Staleness check
+
+Before posting, verify the PR hasn't received new commits since you started:
+
+```bash
+REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
+# HEAD_SHA was captured in pre-flight (step 1)
+CURRENT_HEAD=$(gh pr view <number> --json commits --jq '.commits[-1].oid')
+if [ "$CURRENT_HEAD" != "$HEAD_SHA" ]; then
+ echo "HEAD moved — newer commit will trigger a fresh review"
+ exit 0
+fi
+```
+
+If HEAD moved, skip posting. A newer workflow run will review the latest code.
+
+#### Content filter
+
+Separate internal analysis from postable feedback. The review exists to help the
+author improve the code — not to demonstrate understanding.
+
+- **Post**: Problems found, improvements suggested, questions about intent. Each
+ must be something the author can act on.
+- **Don't post**: Explanations of what the code does, confirmation that the
+ approach is correct, summaries of the change. This is internal analysis.
+
+If the code lacks explanation for future readers, suggest a docstring or
+comment — as a code suggestion, not prose.
+
+If nothing is actionable, use the LGTM behavior (approve with empty body).
+
+#### Confidence-based verdict
+
+After reviewing, check CI status and decide:
+
+```bash
+gh pr view <number> --json statusCheckRollup \
+ --jq '.statusCheckRollup[] | {name: .name, status: .status, conclusion: .conclusion}'
+```
+
+- **Confident** (small, mechanical, well-tested): Approve immediately.
+- **Moderately confident** (non-trivial but looks correct): Approve if CI is
+ green. If CI is pending, submit as COMMENT — don't approve unverified changes.
+- **Unsure** (complex logic, edge cases, untested paths): Run tests locally
+ (`cargo run -- hook pre-merge --yes`) if the toolchain is available. Otherwise
+ submit as COMMENT noting specific concerns.
+
+Factors: small diffs, existing test coverage, and mechanical changes increase
+confidence. New algorithms, concurrency, error handling changes, and untested
+paths decrease it.
+
+#### Posting
+
Submit **one formal review per run** via `gh pr review`. Never call it multiple
times.
@@ -286,10 +337,24 @@ See the review comments for details."
This triggers the `claude-mention` workflow, which checks out the PR branch,
applies fixes, and pushes. CI reruns automatically.
-## How to provide feedback
+## What makes good review feedback
+
+Every comment must be **actionable** — the author can do something with it.
+Apply this filter before posting:
+
+- **Actionable**: "These error messages reference `$XDG_CONFIG_HOME` but the
+ code uses `etcetera` now — the hints are stale" → author can fix this
+- **Actionable**: A code suggestion fixing the stale hint → one-click apply
+- **Not actionable**: "The fix correctly eliminates the duplicate path
+ resolution by delegating to `default_config_path()`" → the author knows this
+
+**Rules:**
-- Use inline review comments for specific code issues. Prefer suggestion format
- (see above) for narrow fixes.
-- Be constructive and explain *why* something should change, not just *what*.
-- Distinguish between suggestions (nice to have) and issues (should fix).
-- Don't nitpick formatting — that's what linters are for.
+- **Don't explain what the code does.** The author wrote it. Explanations add
+ noise, not value.
+- **If the code needs explanation for future readers**, suggest a docstring or
+ inline comment — as a code suggestion.
+- **Use code suggestions** for anything expressible as replacement lines.
+- **Explain *why*** something should change, not just *what*.
+- **Distinguish severity** — "should fix" vs. "nice to have".
+- **Don't nitpick formatting** — that's what linters are for.