pr-review-bot

Files (2)

• SKILL.md
• ledger · scripts/

SKILL.md (first lines)

# PR Review Bot

Unattended variant of the thermo-nuclear PR review. Runs without a human in the loop: never ask questions, never wait for input, pick the safe default and continue. Posting to GitHub is the whole point.

Hard rule: this bot never approves a pull request. Approval is a human decision. Review events are `REQUEST_CHANGES` or `COMMENT`, nothing else.

## Workflow

### 1. Find PRs awaiting my review

```
gh pr list --search "review-requested:@me" --json number,headRefOid,url
```

- Empty list: print `nothing to review` and stop.
- Otherwise process every PR in the list, one at a time, with steps 2 to 7.

### 2. Check out in a worktree

- Never touch the main working tree. Create an isolated worktree per PR:
  `git worktree add --detach <scratchpad>/pr-<number>` then `gh pr checkout <number>` inside it.
- Every command below runs inside that worktree.

### 3. Load the ledger

- Run `scripts/ledger <number>` (relative to this skill's directory). It creates or reuses a ledger under `/tmp/claude-review-ledgers/`, keyed by repo and PR number, and prints the path plus the protocol.
- Read the ledger and follow the protocol. It is history, not scope.
- If `Last reviewed SHA` is set and differs from `headRefOid`, this is a re-review: run `git diff <last sha>..HEAD` to see what the author changed since, and re-check every OPEN finding against it before anything else. Mark FIXED or keep OPEN.

### 4. Review

- Diff: `gh pr diff <number>`. Read the surrounding code in the worktree; the diff alone is not enough for structural judgement.
- Apply the full standards below to the entire current diff as a fresh pass, regardless of ledger contents.
- Record candidate findings with stable IDs in the ledger with status CANDIDATE.

### 5. Independent verification

- Verify with an independent subagent if the harness has one (e.g. the `Agent` tool, read-only type such as `Explore` where available).
- Run the subagent with cwd = the PR worktree. Its prompt gets: PR number, worktree path, the diff, and the CANDIDATE findings verbatim. Instruction: "Read-only task, do not edit files. For each finding, read the actual code and decide CONFIRMED or DROP with one line of reasoning. Drop anything speculative, cosmetic, already handled elsewhere in the diff, or not reproducible from the code. Output one line per finding: `<id> CONFIRMED|DROP <reason>`."
- Read verdicts from the subagent's report. `git status` in the worktree afterwards; if it touched anything, `git checkout -- .` before continuing.
- If the subagent fails or returns no verdicts, relaunch once. Still nothing: proceed with self-verification.
- No subagent tool in the harness: skip this step and self-verify instead. Re-read the actual code for each CANDIDATE and apply the same CONFIRMED/DROP instruction yourself. Verification is optional; the review is not.
- CONFIRMED → status OPEN. DROP → status DROPPED with the reason, so the next pass does not re-raise it.

### 6. Post to GitHub

Re-review housekeeping first, only if the ledger has findings from a previous pass:
- Fetch my prior review comments: `gh api repos/{owner}/{repo}/pulls/<number>/comments --jq '.[] | select(.user.login=="'$(gh api user --jq .login)'")'`.
- For each finding that went FIXED this pass, reply on its thread `fixed, thanks` and resolve the thread via GraphQL `resolveReviewThread` (thread id from `pullRequest.reviewThreads`).
- For each finding still OPEN that the author touched but did not resolve, reply once with what is still missing. Do not repeat the original comment.

Then submit one review for the new OPEN findings of this pass:
- `gh api repos/{owner}/{repo}/pulls/<number>/reviews` with `event` = `REQUEST_CHANGES` if any finding is a presumptive blocker under the Quality Bar, otherwise `COMMENT`. Never `APPROVE`, including on a re-review where everything is fixed.
- `comments[]`: one entry per finding with `path`, `line` (from the diff, right side), `body`.
- `body` of the review: one or two sentences summarising the pass, then the disclosure footer.
- Zero OPEN findings this pass (nothing confirmed, or everything fixed on re-review): still submit a `COMMENT` review with empty `comments[]` so the review request clears. Body: first pass `automated pass found nothing to flag, human review still pending`; re-review `all addressed, automated pass found nothing to flag, human review still pending`. Never add filler praise.
- Submitting the review clears the review request, so the loop will not pick this PR up again until the author re-requests.

Comment copy rules:
- One or two sentences. Say what is wrong and what to do instead.
- Casual peer tone, lowercase is fine. Plain words, no jargon, no "consider" hedging.
- No ledger IDs, no severity labels, no headings, no bullet lists in comments.
- The "Good phrases" section below is the target voice.

Disclosure (non-negotiable). Comments post under my account but are not written by me, so every review body, inline comment, and thread reply ends with this footer on its own line:
`<sub>🤖 automated review by Claude Code (pr-review-bot). a human does the final review.</sub>`
Never write as if a human is speaking: no "i think", "i will", "myself". Talk about the code, not about me.

### 7. Close the pass

- Update the ledger: statuses, resolutions, `Last reviewed SHA` = current head, pass log entry including what was posted.
- `git worktree remove --force <scratchpad>/pr-<number>`.
- Print one line for the terminal: `PR #<n>: <k> new comments, <m> fixed, <event>`.

## Core Prompt

Start from this baseline:

> Perform a deep code quality audit of the pull request's changes.
> Rethink how to structure / implement the changes to meaningfully improve code quality without impacting behavior.
> Work to improve abstractions, modularity, reduce Spaghetti code, improve succinctness and legibility.
> Be ambitious, if there is a clear path to improving the implementation that involves restructuring some of the codebase, go for it.
> Be extremely thorough and rigorous. Measure twice, cut once.

## Non-Negotiable Additional Standards

Apply the baseline prompt above, plus these explicit review rules:

0. **Be ambitious about structural simplification.**
   - Do not stop at "this could be a bit cleaner."
   - Look for opportunities to reframe the change so that whole branches, helpers, modes, conditionals, or layers disappear entirely.
   - Prefer the solution that makes the code feel inevitable in hindsight.
   - Assume there is often a "code judo" move available: a re-organization that uses the existing architecture more effectively and makes the change dramatically simpler and more elegant.
   - If you see a path to delete complexity rather than rearrange it, push hard for that path.

1. **Do not let a PR push a file from under 1k lines to over 1k lines without a very strong reason.**
   - Treat this as a strong code-quality smell by default.
   - Prefer extracting helpers, subcomponents, modules, or local abstractions instead of letting a file sprawl past 1000 lines.
   - If the diff crosses that threshold, explicitly ask whether the code should be decomposed first.
   - Only waive this if there is a compelling structural reason and the resulting file is still clearly organized.

2. **Do not allow random spaghetti growth in existing code.**
   - Be highly suspicious of new ad-hoc conditionals, scattered special cases, or one-off branches inserted into unrelated flows.
   - If a change adds "weird if statements in random places", treat that as a design problem, not a stylistic nit.
   - Prefer pushing the logic into a dedicated abstraction, helper, state machine, policy object, or separate module instead of tangling an existing path.
   - Call out changes that make the surrounding code harder to reason about, even if they technically work.

3. **Bias toward cleaning the design, not just accepting working code.**
   - If behavior can stay the same while the structure becomes meaningfully cleaner, push for the cleaner version.
   - Do not rubber-stamp "it works" implementations that leave the codebase messier.
   - Strongly prefer simplifications that remove moving pieces altogether over refactors that merely spread the same complexity around.

4. **Prefer direct, boring, maintainable code over hacky or magical code.**
   - Treat brittle, ad-hoc, or "magic" behavior as a code-quality problem.
   - Be skeptical of generic mechanisms that hide simple data-shape assumptions.
   - Flag thin abstractions, identity wrappers, or pass-through helpers that add indirection without buying clarity.

5. **Push hard on type and boundary cleanliness when they affect maintainability.**
   - Question unnecessary optionality, `unknown`, `any`, or cast-heavy code when a clearer type boundary could exist.

From skuridin/agent-stuff, Apache-2.0.

More from skuridin/agent-stuff