Add pr-review skill for reviewing remote GitHub PRs and GitLab MRs

AGENTS.md

@@ -16,6 +16,7 @@ This repository contains reusable AI coding workflows that can be installed glob
 - **e2e** — Story-to-tests workflow for [QE] stories (ingest, plan, revise, code, validate, publish, respond)
 - **implement** — Story-to-code workflow (ingest, plan, revise, code, validate, publish, respond)
 - **kcs** — KCS Solution article workflow (gather, draft, validate, handoff)
+- **pr-review** — AI-driven review of a remote GitHub PR or GitLab MR by URL (start, revise, publish, continue, clean)
 - **prd** — Requirements-to-PRD workflow (ingest, clarify, draft, revise, publish, respond)
 - **rebase-stack** — Rebase a stacked-branch chain with conflict guidance, per-branch validation, and push (start, continue, validate, push)
 - **sizing** — Pre-cycle Feature sizing with T-shirt sizes and team effort breakdowns (ingest, assess, apply)
@@ -161,6 +162,7 @@ ai-workflows/
 ├── e2e/
 ├── implement/
 ├── kcs/
+├── pr-review/
 ├── prd/
 ├── rebase-stack/
 ├── sizing/

README.md

@@ -30,6 +30,9 @@ Reusable AI coding workflows a team member can install globally or per-project,
 - **Code Review** -- AI-driven code review for uncommitted changes: discover project conventions, review with an independent reviewer perspective, present findings with honest implementor assessments for human decision, iterate until approved. Supports unattended mode for fully automated review-fix-iterate cycles.
   See [code-review/README.md](code-review/README.md).
 
+- **PR Review** -- AI-driven review of a remote GitHub PR or GitLab MR by URL: check it out into a disposable git worktree, explain context before critiquing, draft inline comments with permalinks/snippets/suggestion blocks, and post only after local approval. Never changes the reviewed code.
+  See [pr-review/README.md](pr-review/README.md).
+
 - **CVE Fix** -- Automated CVE remediation: read vulnerability details from Jira, apply multi-strategy dependency fixes, validate, create pull requests, backport to release branches, and close Jira tickets. Language-agnostic.
   See [cve-fix/README.md](cve-fix/README.md).
 
@@ -112,6 +115,7 @@ Each workflow is intended for a specific project or use case:
 
 - **bugfix** -- the **Flight Control** projects ([flightctl](https://github.com/flightctl/flightctl), [flightctl-ui](https://github.com/flightctl/flightctl-ui))
 - **code-review** -- any project; reviews uncommitted changes against discovered project conventions
+- **pr-review** -- any project; reviews a remote GitHub PR or GitLab MR by URL
 - **docs-writer** -- the [edge-manager](https://gitlab.cee.redhat.com/red-hat-enterprise-openshift-documentation/edge-manager) downstream docs project
 - **prd** -- teams drafting Product Requirements Documents from Jira features
 - **design** -- teams creating technical design documents and Jira-ready epic/story breakdowns from PRDs

pr-review/README.md

@@ -0,0 +1,202 @@
+# PR Review Workflow
+
+An AI-driven review of a remote GitHub pull request or GitLab merge request,
+given its URL. Checks the PR/MR out into a disposable git worktree, always
+explains its context before critiquing it, and drafts inline review comments
+(links, snippets, suggestion blocks) in a suggestive, pluggable tone. Nothing
+is posted until the local user explicitly approves the exact draft content —
+this workflow never changes the reviewed code and never performs a
+host-level PR/MR approval.
+
+## Phase Flow
+
+```mermaid
+graph TD
+    start([start: PR/MR url]) --> draft{Draft review}
+    draft --> revise[revise: Q&A / edits]
+    revise --> draft
+    draft -->|local approval-to-post| publish[publish: post review]
+    publish -->|PR/MR gets new commits| continue[continue: refresh worktree, incremental re-review]
+    continue --> draft
+    clean([clean]) --> removed([worktree + artifacts removed])
+```
+
+## Prerequisites
+
+| Tool | Required | Purpose |
+|------|----------|---------|
+| Git | Yes | Worktree setup, diff analysis |
+| `gh` (GitHub CLI), authenticated | For GitHub PRs | Fetch PR metadata/comments, post the review |
+| `glab` (GitLab CLI), authenticated | For GitLab MRs | Fetch MR metadata/discussions, post comments |
+
+The provider is auto-detected from the URL — you only need whichever CLI
+matches the PR/MR you're reviewing.
+
+## Phases
+
+| Phase | Command | Purpose | Artifact(s) |
+|-------|---------|---------|-------------|
+| Start | `/start {url}` | Detect provider, check out a worktree, gather PR/MR context, draft a review | `00-reviewer-profile.md`, `01-pr-context.md`, `02-draft-review-001.md`, `review-metadata.json`, `decisions-001.json` |
+| Revise | `/revise` | Answer questions, apply edits, add user findings, re-present | `02-draft-review-{NNN}.md`, `decisions-{NNN}.json` |
+| Publish | `/publish` | Post the approved draft as inline review comments | `publish-metadata.json` |
+| Continue | `/continue` | After new commits, refresh the worktree and draft the incremental review | Updated `01-pr-context.md`, `02-draft-review-{NNN}.md`, `decisions-{NNN}.json` |
+| Clean | `/clean` | Remove the worktree, scratch clone (if any), and all artifacts | (removes worktree + artifact directory) |
+
+## Typical Flow
+
+```text
+/start https://github.com/{owner}/{repo}/pull/{n}
+  (or a GitLab MR URL — provider is auto-detected)
+  -> checks out the PR/MR into a git worktree
+  -> gathers PR/MR context (title, author, linked issues, key decisions,
+     existing discussion) and always shows it first
+  -> builds a reviewer profile from the target project's own conventions
+  -> obtains a structured review, extended with permalinks, snippets, and
+     suggestion blocks for every finding
+  -> independently assesses each finding
+  -> drafts inline comments in a suggestive tone
+  -> presents the full draft for local approval-to-post
+
+/revise (repeatable)
+  -> answers your questions about specific comments
+  -> applies edits you request (reword, drop, change suggestions)
+  -> drafts any new findings you describe
+  -> re-presents the updated draft
+
+/publish (only after you approve posting)
+  -> posts the review as inline comments on the host
+  -> worktree is left in place — nothing is torn down here
+
+/continue (after the PR/MR receives new commits)
+  -> refreshes the same worktree in place
+  -> reviews only what's new, notes which prior comments look addressed
+  -> feeds back into /revise -> /publish
+
+/clean (once you're fully done with this PR/MR)
+  -> the only phase that removes the worktree, branch/scratch-clone, and
+     artifacts
+```
+
+## How It Works
+
+### Approve-to-Post, Not PR Approval
+
+"Approve," everywhere in this workflow, means the local user signing off in
+chat on the exact draft content so `/publish` may post it. It is unrelated
+to — and this workflow never performs — a host-level PR/MR approval. Every
+posted GitHub review uses `event: COMMENT` (never `APPROVE`/
+`REQUEST_CHANGES`); the GitLab approve/unapprove endpoint is never called.
+
+### Context Before Critique
+
+Every session starts by writing and presenting `01-pr-context.md`: title,
+author, base↔head, linked issues, a commit narrative, inferred design
+decisions, and a summary of existing discussion. Findings are never shown
+without this context first.
+
+### Findings Extended for Posting
+
+Beyond the standard finding format from `../_shared/review-protocol.md`,
+every kept finding here also carries:
+
+- A **permalink** to the exact line(s) at the PR/MR's head SHA
+- The **quoted snippet** at that location
+- A **suggested-change block** when the fix is a concrete, mechanical
+  replacement — omitted for conceptual or design-level findings. The fence
+  syntax is provider-specific: a bare ` ```suggestion ` block on GitHub, or
+  ` ```suggestion:-{lines_above}+{lines_below} ` on GitLab (see
+  `templates/comment-style.md`).
+
+### Pluggable Comment Style
+
+Posted tone and structure default to suggestive framing ("Should we...",
+never "Do X") with no severity/category labels or "Finding N" headers, and
+a fixed `See comments below` review summary — see
+`templates/comment-style.md`. A reviewed project can override this by
+committing its own `.pr-review/templates/comment-style.md`.
+
+### The Worktree Persists Until `/clean`
+
+Unlike a typical scratch worktree, this one is **not** torn down after
+`/publish`. It stays in place so `/continue` can refresh it (fetch + reset)
+instead of re-cloning from scratch, across as many review rounds as the
+PR/MR goes through. Only `/clean` removes it — run it once you're done
+reviewing a given PR/MR.
+
+### GitHub vs. GitLab
+
+The workflow is almost entirely generic `git` operations plus prose review
+logic. Only a few touchpoints talk to the host directly:
+
+| Touchpoint | GitHub (`gh`) | GitLab (`glab`) |
+|---|---|---|
+| Detect provider | URL path is `/pull/{n}` | URL path is `/-/merge_requests/{n}` |
+| Fetch PR/MR metadata | `gh pr view` | `glab mr view` / `glab api` |
+| Fetch the worktree ref | `refs/pull/{n}/head` | `refs/merge-requests/{n}/head` |
+| List existing comments | `gh api .../pulls/{n}/comments` + `.../reviews` | `glab api .../discussions` |
+| Post the review | One batched review via `gh api .../pulls/{n}/reviews` | One discussion per comment via `glab api .../discussions`, plus a separate summary note |
+
+Everything else — worktree setup, diff analysis, reviewer profile
+discovery, finding drafting, tone/style, the revise loop — has no provider
+branching at all.
+
+## Artifacts
+
+All artifacts and the worktree are stored in
+`.artifacts/pr-review/{context}/`, where `{context}` is a sanitized
+`{owner-or-namespace}-{repo-or-project}-{number}`.
+
+```text
+.artifacts/pr-review/openai-example-repo-1234/
+  00-reviewer-profile.md      (target project's conventions and review focus)
+  01-pr-context.md            (title, author, linked issues, key decisions, existing discussion)
+  review-metadata.json        (provider, refs, iteration, state, timestamps)
+  decisions-001.json          (local decisions per round)
+  02-draft-review-001.md      (draft review, round 1)
+  02-draft-review-002.md      (draft review, round 2 — after /revise or /continue)
+  ...
+  publish-metadata.json       (record of what was posted, once /publish runs)
+  worktree/                   (git worktree checked out at the PR/MR head)
+  _scratch-repo/              (only if no local clone of the target repo could be reused)
+```
+
+## Directory Structure
+
+```text
+pr-review/
+  SKILL.md                     # Workflow entry point
+  guidelines.md                # Behavioral rules and hard limits
+  README.md                    # This file
+  templates/
+    comment-style.md           # Default tone/structure — pluggable
+  skills/
+    controller.md               # Phase dispatcher and transitions
+    start.md                    # URL parsing, worktree setup, context, initial draft
+    revise.md                   # Q&A, edits, user-added findings
+    publish.md                  # Post the approved review
+    continue.md                 # Refresh worktree, incremental re-review
+    clean.md                    # Remove worktree + artifacts
+  commands/
+    start.md                    # /start command
+    revise.md                   # /revise command
+    publish.md                  # /publish command
+    continue.md                 # /continue command
+    clean.md                    # /clean command
+```
+
+## Getting Started
+
+```bash
+# Install the workflow
+./install.sh claude --workflows pr-review
+
+# Or install all workflows
+./install.sh all
+```
+
+Then run the `pr-review` workflow's `start` command with a PR or MR URL:
+
+```text
+/start https://github.com/{owner}/{repo}/pull/{number}
+/start https://gitlab.com/{namespace}/{project}/-/merge_requests/{number}
+```

pr-review/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: pr-review
+version: 0.2.1
+description: >-
+  AI-driven review of a remote pull request or merge request, given its URL
+  (GitHub or GitLab, auto-detected). Checks out the PR/MR into a git worktree,
+  explains PR context and key decisions, evaluates changes using the shared
+  code-review protocol, and drafts inline review comments (with code links,
+  snippets, and suggested-change blocks) in a pluggable, suggestive tone.
+  Always presents the draft for local approval before posting a review, never
+  changes the reviewed code, supports revision based on questions or new
+  findings, and can resume after the PR/MR receives new commits. Use when
+  asked to review, comment on, or give feedback on a GitHub PR or GitLab MR
+  URL. Activated by commands: /start, /revise, /publish, /continue, /clean.
+---
+# PR Review Workflow Orchestrator
+
+## Quick Start
+
+1. If the user invoked a specific command (e.g., `/start`, `/revise`), read
+   `commands/{command}.md` and follow it.
+2. Otherwise, read `skills/controller.md` to load the workflow controller and
+   follow its dispatch logic.
+
+If a step fails or produces unexpected output, stop and report the error to
+the user. Do not advance to the next phase. Offer to retry or escalate.
+
+For principles, hard limits, safety, quality, and escalation rules, see `guidelines.md`.

pr-review/commands/clean.md

@@ -0,0 +1,11 @@
+---
+name: pr-review:clean
+description: "Remove the worktree and all review artifacts for a PR/MR"
+---
+# /clean
+
+Read `../skills/controller.md` and follow it.
+
+Dispatch the **clean** phase. Context:
+
+$ARGUMENTS

pr-review/commands/continue.md

@@ -0,0 +1,11 @@
+---
+name: pr-review:continue
+description: "Refresh the worktree after new commits and draft a review of what's new"
+---
+# /continue
+
+Read `../skills/controller.md` and follow it.
+
+Dispatch the **continue** phase. Context:
+
+$ARGUMENTS

pr-review/commands/publish.md

@@ -0,0 +1,11 @@
+---
+name: pr-review:publish
+description: "Post the approved draft as a review with inline comments on the host"
+---
+# /publish
+
+Read `../skills/controller.md` and follow it.
+
+Dispatch the **publish** phase. Context:
+
+$ARGUMENTS

pr-review/commands/revise.md

@@ -0,0 +1,11 @@
+---
+name: pr-review:revise
+description: "Answer questions, apply edits, add findings, and re-present the draft review"
+---
+# /revise
+
+Read `../skills/controller.md` and follow it.
+
+Dispatch the **revise** phase. Context:
+
+$ARGUMENTS

pr-review/commands/start.md

@@ -0,0 +1,11 @@
+---
+name: pr-review:start
+description: "Check out a PR/MR from its URL into a worktree, gather context, and draft a review"
+---
+# /start
+
+Read `../skills/controller.md` and follow it.
+
+Dispatch the **start** phase. Context:
+
+$ARGUMENTS