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.mdindex 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:```bashREPO=$(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:```bashREPO=$(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 multipletimes.@@ -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.