Add PR review mode to code-review workflow

code-review/README.md

@@ -1,24 +1,42 @@
 # Code Review Workflow
 
-An AI-driven code review workflow that reviews uncommitted changes, presents findings for human decision, and iterates until approved or the user declares done.
+An AI-driven code review workflow with two modes:
+
+- **Local review** -- reviews uncommitted changes, presents findings for human decision, and iterates until approved or the user declares done.
+- **PR review** -- reviews GitHub Pull Requests with deep cross-file analysis and optionally posts findings as GitHub review comments.
 
 ## Prerequisites
 
-| Tool | Required | Purpose |
-|------|----------|---------|
-| Git | Yes | Diff analysis, branch detection |
+| Tool | Required For | Purpose |
+|------|-------------|---------|
+| Git | Local review | Diff analysis, branch detection |
+| `gh` (GitHub CLI) | PR review | Fetch PR contents, post review comments |
 
-No external services (Jira, GitHub CLI) are required. The workflow operates entirely on local uncommitted changes. If the project has discoverable lint or test commands, they are run during `/continue` to validate changes.
+Local review operates entirely on local uncommitted changes with no external services. PR review requires an authenticated `gh` CLI with access to the target repository. If the project has discoverable lint or test commands, they are run during `/continue` to validate changes.
 
 ## Phases
 
+### Local Review
+
 | Phase | Command | Purpose | Artifact(s) |
 |-------|---------|---------|-------------|
 | Start | `/start` | Discover project, review changes, present findings | `00-reviewer-profile.md`, `01-change-summary.md`, `code-review-001.md`, `review-metadata.json`, `decisions-001.json` |
 | Continue | `/continue` | Implement accepted changes, re-review | `review-response-{NNN}.md`, `code-review-{NNN}.md`, `decisions-{NNN}.json` |
+
+### PR Review
+
+| Phase | Command | Purpose | Artifact(s) |
+|-------|---------|---------|-------------|
+| PR | `/pr` | Review a GitHub PR with deep analysis | `pr-review-metadata.json`, `pr-review-001.md` |
+| PR Continue | `/pr-continue` | Re-review after author pushes fixes | Updated `pr-review-metadata.json`, `pr-review-{NNN}.md` |
+
+### Shared
+
+| Phase | Command | Purpose | Artifact(s) |
+|-------|---------|---------|-------------|
 | Clean | `/clean` | Remove artifacts from abandoned reviews | (removes artifact directory) |
 
-## Typical Flow
+## Typical Flow -- Local Review
 
 ```text
 /start [optional focus guidance]
@@ -44,15 +62,39 @@ No external services (Jira, GitHub CLI) are required. The workflow operates enti
   -> removes .artifacts/code-review/{branch}/
 ```
 
+## Typical Flow -- PR Review
+
+```text
+/pr https://github.com/owner/repo/pull/123
+  -> fetches PR metadata, diff, and full file contents via gh
+  -> loads existing review comments to avoid duplication
+  -> reads project conventions
+  -> performs deep cross-file analysis
+  -> presents findings conversationally (no severity labels or formal tables)
+  -> offers to post findings as GitHub review comments
+
+(author pushes fixes)
+
+/pr-continue
+  -> fetches changes since last review (interdiff)
+  -> checks what was fixed, what remains, what's new
+  -> presents updated findings with progress notes
+  -> offers to post follow-up review or approve
+
+(repeat until satisfied)
+
+/clean (optional -- removes .artifacts/code-review/pr-{number}/)
+```
+
 ## How It Works
 
 ### Project Discovery
 
-On first run, the workflow reads the project's AGENTS.md, CLAUDE.md, CONTRIBUTING.md, linting configs, and CI workflows to build a reviewer profile. This profile determines what the reviewer focuses on and what conventions it enforces. No manual initialization needed.
+On first run, the workflow reads the project's AGENTS.md, CLAUDE.md, CONTRIBUTING.md, linting configs, and CI workflows to build a reviewer profile. This profile determines what the reviewer focuses on and what conventions it enforces. No manual initialization needed. Both local and PR review modes use this discovery step.
 
-### The Decision Table
+### Local Review: The Decision Table
 
-After each review round, findings are presented in a structured table with both the reviewer's finding and the implementor's independent assessment:
+After each local review round, findings are presented in a structured table with both the reviewer's finding and the implementor's independent assessment:
 
 ```text
 | # | Severity | Category | Finding | Implementor Assessment | Recommendation |
@@ -63,21 +105,35 @@ After each review round, findings are presented in a structured table with both
 
 The user makes the final call on every finding.
 
+### PR Review: Conversational Findings
+
+PR review uses a different presentation model. Findings are presented conversationally without severity labels, formal tables, or implementor assessments. Each finding states what the issue is, why it matters, and what to change. The goal is findings the author would actually fix, not a comprehensive checklist.
+
+PR review also reads full file contents (not just diffs) to catch issues that only emerge from understanding the surrounding code.
+
 ### Reviewer Independence
 
-When the AI runtime supports subagents, the review is performed by a separate agent with its own context. This reduces the tendency to rationalize decisions made during implementation, though a same-model subagent shares the same weights and training biases — it is not equivalent to an independent human reviewer or a different tool. The subagent is strongest at catching mechanical issues: convention violations, obvious bugs, inconsistencies with surrounding code, and missed edge cases.
+When the AI runtime supports subagents, the local review is performed by a separate agent with its own context. This reduces the tendency to rationalize decisions made during implementation, though a same-model subagent shares the same weights and training biases — it is not equivalent to an independent human reviewer or a different tool. The subagent is strongest at catching mechanical issues: convention violations, obvious bugs, inconsistencies with surrounding code, and missed edge cases.
 
 When subagents are not available, the review is performed sequentially within the same context. The file-based protocol is the same either way.
 
+PR review does not use the dual-role model -- it operates as a single reviewer perspective.
+
 For genuinely independent review, pair this workflow with external tools (e.g., coderabbit) and human reviewers.
 
 ### Automatic Cleanup
 
-When the reviewer approves and the user confirms, all artifacts in `.artifacts/code-review/{branch}/` are removed. The `/clean` command exists only as an escape hatch for reviews that are started but never completed.
+For local review, when the reviewer approves and the user confirms, all artifacts in `.artifacts/code-review/{branch}/` are removed.
+
+For PR review, cleanup is offered but not automatic -- the user may want to keep the review history across rounds.
+
+The `/clean` command works for both modes as an escape hatch for reviews that are started but never completed.
 
 ## Artifacts
 
-All artifacts are stored in `.artifacts/code-review/{branch}/`.
+### Local Review
+
+Stored in `.artifacts/code-review/{branch}/`:
 
 ```text
 .artifacts/code-review/feature-xyz/
@@ -91,6 +147,18 @@ All artifacts are stored in `.artifacts/code-review/{branch}/`.
   ...
 ```
 
+### PR Review
+
+Stored in `.artifacts/code-review/pr-{number}/`:
+
+```text
+.artifacts/code-review/pr-123/
+  pr-review-metadata.json    (PR number, head SHA, round, owner/repo)
+  pr-review-001.md           (findings from round 1)
+  pr-review-002.md           (findings from round 2, after author pushes)
+  ...
+```
+
 ## Optional Focus Guidance
 
 When starting a review, you can provide focus guidance:
@@ -129,12 +197,16 @@ code-review/
   README.md                    # This file
   skills/
     controller.md              # Phase dispatcher and transitions
-    start.md                   # Project discovery + initial review
-    continue.md                # Implement changes + re-review
+    start.md                   # Local: project discovery + initial review
+    continue.md                # Local: implement changes + re-review
+    pr.md                      # PR: deep analysis + optional GitHub posting
+    pr-continue.md             # PR: re-review after author pushes fixes
     clean.md                   # Remove abandoned review artifacts
   commands/
-    start.md                   # /start command
-    continue.md                # /continue command
+    start.md                   # /start command (local review)
+    continue.md                # /continue command (local review)
+    pr.md                      # /pr command (PR review)
+    pr-continue.md             # /pr-continue command (PR re-review)
     clean.md                   # /clean command
 ```
 
@@ -148,4 +220,13 @@ code-review/
 ./install.sh all
 ```
 
-Then in your project, make some changes and run the `code-review` workflow's `start` command.
+**Local review:** Make some changes and run `/start`.
+
+**PR review:** Run `/pr` with a PR URL or number:
+
+```text
+/pr https://github.com/owner/repo/pull/123
+/pr 123
+```
+
+After the author pushes fixes, run `/pr-continue` to re-review.

code-review/SKILL.md

@@ -1,18 +1,21 @@
 ---
 name: code-review
 description: >-
-  AI-driven code review workflow that reviews uncommitted changes using a
-  discoverable reviewer profile, presents findings for human decision, and
-  iterates until approved. Supports --unattended for automated iteration.
-  Use when reviewing code before commit or PR.
-  Activated by commands: /start, /continue, /clean.
+  AI-driven code review workflow. Reviews uncommitted local changes or GitHub
+  Pull Requests. Local mode uses a discoverable reviewer profile with
+  iterative human decisions; PR mode performs deep cross-file analysis and
+  optionally posts findings as GitHub review comments. Supports --unattended
+  for local review automation.
+  Use when reviewing code before commit, reviewing PRs, or posting review
+  comments to GitHub.
+  Activated by commands: /start, /continue, /pr, /pr-continue, /clean.
 ---
 # Code Review Workflow Orchestrator
 
 ## Quick Start
 
-1. If the user invoked a specific command (e.g., `/start`, `/continue`), read
-   `commands/{command}.md` and follow it.
+1. If the user invoked a specific command (e.g., `/start`, `/continue`, `/pr`,
+   `/pr-continue`), read `commands/{command}.md` and follow it.
 2. Otherwise, read `skills/controller.md` to load the workflow controller and
    follow its dispatch logic.
 

code-review/commands/pr-continue.md

@@ -0,0 +1,11 @@
+---
+name: code-review:pr-continue
+description: "Re-review a PR after the author pushes fixes, building on previous round context"
+---
+# /pr-continue
+
+Read `../skills/controller.md` and follow it.
+
+Dispatch the **pr-continue** phase. Context:
+
+$ARGUMENTS

code-review/commands/pr.md

@@ -0,0 +1,11 @@
+---
+name: code-review:pr
+description: "Review a GitHub Pull Request with deep analysis and optional comment posting"
+---
+# /pr
+
+Read `../skills/controller.md` and follow it.
+
+Dispatch the **pr** phase. Context:
+
+$ARGUMENTS

code-review/guidelines.md

@@ -14,6 +14,16 @@ are specific to the interactive code-review workflow.
 - **Scope is about relevance, not mechanics.** The review covers all uncommitted changes, but not every file in the workspace is necessarily part of the change. Determine relevance by examining each file's content and its relationship to the logical change — not by a mechanical staged/unstaged filter.
 - **The review is private.** All artifacts stay in `.artifacts/` (gitignored). Review iterations are working documents, not public records.
 
+### PR Review Principles
+
+These apply specifically to `/pr` and `/pr-continue`:
+
+- **PR review is read-only.** No local code changes, no git mutations. The author fixes their own code on their branch.
+- **Single perspective.** No implementor assessment or dual-role debate. One sharp reviewer voice. The user is reading your review to decide whether to relay it to the PR author, not to mediate an internal discussion.
+- **Respect existing comments.** Read existing review comments before analyzing. Do not duplicate what has already been said unless the issue was not fixed.
+- **No quota.** If the PR is clean, say so. Do not manufacture findings to fill a template or justify the review's existence.
+- **Depth over breadth.** A few findings the author will actually fix are worth more than a long list they will dismiss. Prioritize correctness bugs, silent failures, and cross-file inconsistencies over style preferences and theoretical concerns.
+
 ## Hard Limits
 
 - No auto-advancing between phases. Always wait for the user.
@@ -22,13 +32,16 @@ are specific to the interactive code-review workflow.
 - No fabricated findings. Every issue cited must reference a specific file and location in the actual diff.
 - No scope creep. The reviewer reviews what changed, not what didn't.
 - No mutating git operations (commit, push, branch, checkout) during `/start`. Read-only git commands (`git diff`, `git log`, `git ls-files`) are expected. Code changes happen only in `/continue`.
+- **PR reviews: no GitHub comments without preview.** `/pr` and `/pr-continue` must show a full preview of what will be posted and wait for user confirmation before posting any review comments to GitHub.
+- **PR reviews: no local code changes.** `/pr` and `/pr-continue` never modify local files. They are strictly read-only phases that analyze remote code.
 
 ## Safety
 
 - Read the project's `AGENTS.md`, `CLAUDE.md`, and contribution guidelines before reviewing. Project conventions override general preferences.
 - Verify that each finding references real code. If a finding cites a file or line that doesn't exist in the diff, discard it.
 - When the implementor disagrees with a finding, present both perspectives to the user with evidence. Do not silently drop findings or silently accept them.
 - Before applying code changes in `/continue`, read the affected file to confirm the change is still valid (the file may have been modified between rounds).
+- For PR reviews, verify that referenced files and lines exist in the PR diff before presenting findings or posting comments. The `gh api` content fetch may fail for deleted files or renamed paths -- handle gracefully.
 
 ## Quality
 
@@ -45,6 +58,8 @@ Stop and request human guidance when:
 - The reviewer and implementor disagree on a CRITICAL finding
 - The changes affect security-sensitive code and the reviewer is uncertain
 - The project has no discoverable conventions and the reviewer cannot calibrate
+- For PR reviews: the `gh` CLI is not authenticated or the PR is not accessible
+- For PR reviews: the PR has 50+ changed files (suggest reviewing in logical groups)
 
 ## Working With the Project
 

code-review/skills/clean.md

@@ -10,47 +10,59 @@ review that was abandoned or is no longer needed.
 
 ## Your Role
 
-Find and remove review artifacts for the current branch. This command is
-only needed when a review was started but not completed through the normal
-`/continue` approval flow (which cleans up automatically).
+Find and remove review artifacts from local reviews (branch-scoped) or PR
+reviews (PR-number-scoped). This command is only needed when a review was
+started but not completed through the normal approval flow.
 
 ## Critical Rules
 
 - **Only delete artifacts.** Do not modify any project files.
 - **Confirm before deleting.** Show the user what will be removed and wait
   for confirmation.
-- **Branch-scoped.** Only clean artifacts for the current branch unless the
-  user specifies otherwise.
+- **Scoped cleanup.** Clean artifacts for the current context (branch or PR
+  number) unless the user specifies otherwise.
 
 ## Process
 
-### Step 1: Identify Current Branch
+### Step 1: Determine Cleanup Target
+
+Check `$ARGUMENTS` for a PR number or URL. If present, extract the PR
+number and set the target to `.artifacts/code-review/pr-{number}/`.
+
+If `$ARGUMENTS` is empty or does not contain a PR reference, determine the
+current branch:
 
 ```bash
 git branch --show-current
 ```
 
+Check for artifacts in both locations:
+- `.artifacts/code-review/{branch}/` (local review)
+- `.artifacts/code-review/pr-*/` (PR reviews -- list any that exist)
+
+If both local and PR artifacts exist, present them separately and ask the
+user which to clean (or both).
+
 ### Step 2: Check for Artifacts
 
-Check if `.artifacts/code-review/{branch}/` exists.
+For the identified target(s), check if the directory exists.
 
-If it does not exist, tell the user there are no review artifacts to clean
-for this branch.
+If no artifacts exist, tell the user there are no review artifacts to clean.
 
 ### Step 3: Show What Will Be Removed
 
 List all files in the artifact directory:
 
 ```bash
-ls -la .artifacts/code-review/{branch}/
+ls -la {artifact_directory}
 ```
 
-Present the list to the user:
+Present the list to the user. For local review:
 
 ```markdown
 ## Review artifacts to remove
 
-Branch: {branch}
+**Local review** -- Branch: {branch}
 
 | File | Description |
 |------|-------------|
@@ -64,12 +76,28 @@ Branch: {branch}
 Confirm removal? (This cannot be undone.)
 ```
 
+For PR review:
+
+```markdown
+## Review artifacts to remove
+
+**PR review** -- PR #{number}
+
+| File | Description |
+|------|-------------|
+| pr-review-metadata.json | PR review state |
+| pr-review-001.md | PR review round 1 |
+| pr-review-002.md | PR review round 2 |
+
+Confirm removal? (This cannot be undone.)
+```
+
 ### Step 4: Remove Artifacts
 
 After user confirmation:
 
 ```bash
-rm -rf .artifacts/code-review/{branch}
+rm -rf {artifact_directory}
 ```
 
 Clean up any empty parent directories left behind (handles branch names
@@ -83,7 +111,8 @@ Tell the user the artifacts have been removed.
 
 ## Output
 
-- Removed `.artifacts/code-review/{branch}/` directory
+- Removed artifact directory (local: `.artifacts/code-review/{branch}/`,
+  PR: `.artifacts/code-review/pr-{number}/`)
 
 ## When This Phase Is Done