/pr-review
Reviews the branch against project guidelines, fixes issues, and keeps .claude/rules/ fresh.
User context
User-provided context for this invocation: $ARGUMENTS
If non-empty, treat it as a lens across every step — e.g. "focus on the streaming changes" means weight Step 2's review and Step 5's rule-freshness pass toward that area. Don't skip steps because of it.
Step 1: Set up the diff
git branch --show-current. If on main, check for uncommitted or staged changes. If there are changes, ask the user for a branch name, create it, and continue. If there are none, stop — nothing to review.git fetch upstream main, then collect the diff: git diff upstream/main...HEAD, git diff, git diff --cached, plus untracked files from git status --short. Uncommitted work is in scope.
Diff against upstream/main, never the local main ref: local main lags as soon as someone merges, which silently pulls their shipped commits into your review. (origin is a personal fork; upstream is AllYourBot/hostedgpt.)
If the branch holds unrelated work (e.g. an earlier commit for a different change), say so and review only the work the user is asking about.
Step 2: Review against the guidelines
- Read
CLAUDE.md and every .claude/rules/*.md. They are path-scoped, but read all of them for review so you can apply the right guidance to every changed file.
- Review all changes against them. Also look for bugs, security issues (never log raw tokens;
encrypts on credentials), dead code, and missing test coverage — including the CLAUDE.md conventions: provider behavior stays in the AIBackend layer, provider tests stub the client under test/support/test_client/, and streaming changes assert chunk order as well as final persistence.
- Verify each finding against the full file before acting on it — a diff alone often suggests problems the surrounding code disproves.
- Fix every real issue. New tests follow the rule for their file type:
unit_test.md + model_concern.md for models and concerns, controller_test.md for controllers, tests.md everywhere.
For a large diff you may fan the analysis out to subagents via the Agent tool (e.g. one per area). If you do, they are ANALYSIS ONLY — tell them explicitly not to use Edit or Write and to return proposed replacement text with file:line. You apply every edit yourself.
Step 3: Strip comments to load-bearing only
For every comment added on this branch, ask: "If I delete this comment, would a future developer plausibly break something or waste meaningful time?"
Default action is REMOVE. Keep a comment only when you can finish the sentence "Without this comment, a future dev would…" with a concrete failure — a hidden coupling, a workaround for a specific bug, a surprising invariant. Comments that restate the code, summarize the method, or record write-time thinking go.
Step 4: Tighten consecutive one-line method definitions
Consecutive single-expression def foo = expr definitions in the same scope sit with no blank lines between them. Don't collapse a one-liner against a multi-line def, or across another statement (an attr_*, a constant, a comment).
Step 5: Keep .claude/rules/ fresh
- ADD: Did the review catch a mistake a competent person could make again? Did the diff hit a non-obvious gotcha or settle a decision where the obvious alternative fails? Document it in the most narrowly-scoped rule that covers those paths (or CLAUDE.md for architecture).
- UPDATE: Does a rule contradict what the code actually does? Figure out which side is wrong and fix it.
- REMOVE: References to files, helpers, or tools that no longer exist; guidance now redundant. When in doubt, delete.
Don't add descriptions of what code does, standard conventions, or "useful background" — the bar is load-bearing. Most PRs need 0–1 small rule edits.
Step 6: Run the tests
Run bin/rails test and bin/rubocop (and bin/blocks test if app/javascript/blocks/ changed). System tests run in CI on the PR. Fix failures before committing; report any you can't fix.
Step 7: Commit
If Steps 2–5 changed anything, stage the files explicitly and commit with a message describing the review changes, separate from feature commits.
Step 8: Link the PR
End with the PR URL (gh pr view --json url -q .url). If no PR exists yet, say so and suggest /pr.