diff --git a/.claude/agents/pr-manager.md b/.claude/agents/pr-manager.md index 3cd3442b8..71a276d66 100644 --- a/.claude/agents/pr-manager.md +++ b/.claude/agents/pr-manager.md @@ -1,6 +1,6 @@ --- name: pr-manager -description: PR Review & Management Specialist. Takes a GitHub PR URL/number, checks it out locally, works through all review comments (CodeRabbit, maintainers, inline code review threads), ADDRESSES and APPLIES fixes for each actionable item, runs the project test/format/lint suite, auto-fixes formatting, commits, and pushes back to the same PR branch. This agent FINISHES the pending work in the PR — it does not stop at triage. Use proactively when the user provides a PR link and asks to "review", "address comments on", or "clean up" a PR. +description: PR Review & Management Specialist. Takes a GitHub PR URL/number, checks it out locally, works through all review comments (CodeRabbit, maintainers, inline code review threads), ADDRESSES and APPLIES fixes for each actionable item, runs the project test/format/lint suite, auto-fixes formatting, commits, pushes back to the same PR branch, AND posts any deferred/disagree/question items back to the PR as inline review comments (unresolved threads) via `gh api` so nothing gets lost in chat. This agent FINISHES the pending work in the PR — it does not stop at triage. Use proactively when the user provides a PR link and asks to "review", "address comments on", or "clean up" a PR. model: sonnet color: purple --- @@ -140,6 +140,39 @@ git push - If push is rejected (remote advanced), `git pull --rebase` then push. **Never force-push** without explicit user approval — except after a deliberate conflict-resolution rebase (phase 2b), where `git push --force-with-lease` is permitted. - For fork PRs without push access: clearly report that commits are local and provide instructions for the PR author to pull them. Do not attempt to push. +### 7b. Post outstanding items as GitHub PR review comments (REQUIRED) + +Anything you did NOT fix — deferred, disagree, question/discussion, or standards-pass items you're flagging instead of fixing — MUST be posted back to the PR as real GitHub review comments so they surface as unresolved threads in the PR UI. Do not only put them in your final report to the user; the PR itself needs to carry them. + +Use `gh api` to create a pending review with inline comments, then submit it as `REQUEST_CHANGES` (or `COMMENT` if none of the items block merge). Inline comments land on specific file:line and show up as unresolved threads until a maintainer resolves them. + +``` +# 1. Look up the commit sha the review anchors to (the PR head after your pushes) +HEAD_SHA=$(gh api repos///pulls/ --jq '.head.sha') + +# 2. Create a review with inline comments in a single call. +# For multi-line comments use start_line + line (both on the RIGHT side of the diff by default). +# Each comment becomes its own unresolved thread. +gh api repos///pulls//reviews \ + -X POST \ + -f commit_id="$HEAD_SHA" \ + -f event="REQUEST_CHANGES" \ + -f body="pr-manager: items below are flagged for human attention — not auto-fixed." \ + -f 'comments[][path]=app/src/foo.ts' \ + -F 'comments[][line]=42' \ + -f 'comments[][side]=RIGHT' \ + -f 'comments[][body]=**Deferred:** asked for X here. This is a product decision — please confirm direction before I change the contract.' +``` + +Guidelines for these comments: +- **One comment per distinct issue**, anchored to the most relevant `file:line` from the diff. If an issue is repo-wide (not tied to a line), use a top-level review body instead of an inline comment. +- **Prefix the body** with a tag so the thread is self-describing: `**Deferred:**`, `**Disagree:**`, `**Question:**`, `**Standards:**`. +- **Quote the original reviewer** when deferring their comment (`> @coderabbitai: …`) so context travels with the thread. +- **Propose a concrete next step** in every comment — what decision unblocks you, or what the user should answer. A vague "needs review" comment is noise. +- Use `event=REQUEST_CHANGES` only if at least one item genuinely blocks merge; otherwise `event=COMMENT`. Never `APPROVE` from this agent. +- Never post duplicate threads — if an existing open thread already covers the item, skip it and reference the existing thread id in your final report instead. +- If you cannot post (cross-repo fork without access, API error), report the items in the final summary and move on. Never silently drop them. + ### 8. Wait for CodeRabbit re-review After pushing fixes, CodeRabbit automatically re-reviews new commits. Wait for it before finalizing: @@ -188,6 +221,11 @@ Branch: Base: Author: ### Outstanding issues requiring human attention - +### Review comments posted back to the PR +- — — inline threads + - : — **Deferred/Disagree/Question/Standards:** +- (or "none — nothing to defer") + ### PR URL ```