# Review Pr

> Review a GitHub PR using multi-agent verification. Usage /groundwork:review-pr [PR number or URL]. Pass --no-interactive to skip all prompts and auto-publish.

- **Type:** Skill
- **Install:** `agentstack add skill-etr-groundwork-review-pr`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [etr](https://agentstack.voostack.com/s/etr)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [etr](https://github.com/etr)
- **Source:** https://github.com/etr/groundwork/tree/main/skills/review-pr

## Install

```sh
agentstack add skill-etr-groundwork-review-pr
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# PR Review Skill

Multi-agent PR review that runs specialized agents against PR changes and posts structured feedback to GitHub.

## Non-Interactive Mode Detection

Check for non-interactive mode from either source:
1. If the argument string contains `--no-interactive` → strip it from the argument before PR number parsing, set `non_interactive = true`
2. If session context contains `GROUNDWORK_BATCH_MODE=true` → set `non_interactive = true`

If either condition is met, all `AskUserQuestion` prompts below are replaced with their documented auto-decision — **except** the pre-flight model check, which always prompts.

## Pre-flight: Model Recommendation

**Your current effort level is `{{effort_level}}`.**

Skip this step silently if effort is `high`, `xhigh`, or `max` (the scale is `low`  --json title,body,baseRefName,headRefName,headRefOid,author,state,url,isCrossRepository,additions,deletions,changedFiles
   ```

2. **PR diff**:
   ```bash
   gh pr diff 
   ```
   Store as `pr_diff`.

3. **Changed file paths**:
   ```bash
   gh pr view  --json files --jq '.files[].path'
   ```
   Store as `changed_file_paths`.

4. **Diff stat**:
   ```bash
   gh pr diff  --stat
   ```
   Store as `diff_stat`.

5. **Existing reviews**:
   ```bash
   gh api repos//pulls//reviews
   ```
   Store as `existing_reviews`.

6. **Existing review comments**:
   ```bash
   gh api repos//pulls//comments
   ```
   Store as `existing_comments`.

**Validate state:**
- If the PR state is not `OPEN`:
  - **Non-interactive mode:** Log a warning ("PR is [state] — continuing anyway") and proceed.
  - **Interactive mode:** Use `AskUserQuestion`:
    ```json
    {
      "questions": [{
        "question": "This PR is **[state]**. Continue reviewing anyway?",
        "header": "PR is not open",
        "options": [
          { "label": "Yes, continue" },
          { "label": "Cancel" }
        ],
        "multiSelect": false
      }]
    }
    ```
    If "Cancel" → stop.
- If `isCrossRepository` is true, run `gh pr checkout ` to fetch the fork's branch.
- Otherwise, checkout the PR branch: `gh pr checkout `.

## Step 3: Handle Existing Feedback

### 3a: Detect Previous Groundwork Reviews

Search `existing_reviews` for reviews whose body contains the marker ``.

**If groundwork reviews exist:**

- **Non-interactive mode:** Proceed with a fresh review (default).
- **Interactive mode:** Use `AskUserQuestion`:
  ```json
  {
    "questions": [{
      "question": "Previous groundwork review(s) found on this PR. How would you like to proceed?",
      "header": "Existing groundwork reviews detected",
      "options": [
        { "label": "Fresh review", "description": "Post a fresh review (dismisses previous)" },
        { "label": "Incremental review", "description": "Only new findings since last groundwork review" },
        { "label": "Cancel" }
      ],
      "multiSelect": false
    }]
  }
  ```

If "Fresh review" → proceed normally.
If "Incremental review" → store previous groundwork findings to exclude duplicates in Step 6.
If "Cancel" → stop.

### 3b: Summarize Non-Groundwork Feedback

If non-groundwork reviews or review comments exist, produce a brief summary as `existing_human_feedback`. Include:
- Reviewer name and verdict (APPROVED, CHANGES_REQUESTED, COMMENTED)
- Key points raised

This summary will be passed to agents so they avoid restating already-raised points.

### 3c: Handle Replies on Previous Groundwork Comments

If `existing_comments` contain replies to previous groundwork-authored comments (detected by `` marker or matching author):
- Present these reply threads to the user
- Recommend responses and paths forward before proceeding with the new review

## Step 4: Determine Active Agents

Parse `changed_file_paths` to determine which conditional agents to enable:

| Agent | Active | Skip when |
|-------|--------|-----------|
| `code-quality-reviewer` | Always | -- |
| `test-quality-reviewer` | Always | -- |
| `security-reviewer` | Always | -- |
| `performance-reviewer` | Always | -- |
| `code-simplifier` | Always | -- |
| `housekeeper` | Always | -- |
| `architecture-alignment-checker` | Conditional | No architecture docs found at `{{specs_dir}}/` |
| `design-consistency-checker` | Conditional | No design system docs AND no CSS/styling files in `changed_file_paths` |
| `cloud-infrastructure-reviewer` | Conditional | No IaC/config files in `changed_file_paths` |
| `conventions-reviewer` | Conditional | No CLAUDE.md files found in the repo |

**Skip `spec-alignment-checker`** — it performs internal EARS requirement tracing which is not relevant to PR review.

Check for architecture and design docs:
- Architecture: look for `{{specs_dir}}/architecture.md` or `{{specs_dir}}/architecture/`
- Design system: look for `{{specs_dir}}/design_system.md` or `{{specs_dir}}/design_system/`

Record skipped agents with reason in the aggregation table (verdict: `skipped`).

## Step 5: Launch Agents in Parallel

**CRITICAL — Context budget**: Do NOT read file contents, full diffs, or docs into this orchestrating context. Collect only file paths and metadata. Agents have Read/Grep/Glob tools and will read files in their own context windows.

Spawn all active agents **in parallel** using the `Agent` tool with `subagent_type`. Each agent receives:

| Agent (`subagent_type`) | Context to Provide |
|-------------------------|-------------------|
| `groundwork:code-quality-reviewer:code-quality-reviewer` | `changed_file_paths`, `diff_stat`, `pr_description`, `existing_human_feedback` |
| `groundwork:test-quality-reviewer:test-quality-reviewer` | `changed_file_paths`, `diff_stat`, `pr_description`, `existing_human_feedback` |
| `groundwork:security-reviewer:security-reviewer` | `changed_file_paths`, `diff_stat`, `pr_description`, `existing_human_feedback` |
| `groundwork:performance-reviewer:performance-reviewer` | `changed_file_paths`, `diff_stat`, `pr_description`, `existing_human_feedback` |
| `groundwork:code-simplifier:code-simplifier` | `changed_file_paths`, `diff_stat`, `pr_description`, `existing_human_feedback` |
| `groundwork:housekeeper:housekeeper` | `changed_file_paths`, `diff_stat`, `pr_description`, `existing_human_feedback` |
| `groundwork:architecture-alignment-checker:architecture-alignment-checker` | `changed_file_paths`, `diff_stat`, `pr_description`, `architecture_path`, `existing_human_feedback` |
| `groundwork:design-consistency-checker:design-consistency-checker` | `changed_file_paths`, `diff_stat`, `pr_description`, `design_system_path`, `existing_human_feedback` |
| `groundwork:cloud-infrastructure-reviewer:cloud-infrastructure-reviewer` | `changed_file_paths`, `diff_stat`, `pr_description`, `architecture_path`, `existing_human_feedback` |
| `groundwork:conventions-reviewer:conventions-reviewer` | `changed_file_paths`, `diff_stat`, `pr_description`, `existing_human_feedback` |

**In each agent prompt, include these instructions:**

> Use the Read tool to examine these files. Do NOT expect file contents in this prompt — read them yourself.
>
> **PR Review context**: You are reviewing a pull request, not a local task implementation. The `pr_description` below replaces `task_definition`. Focus ONLY on code within the PR diff. Do not flag issues in unchanged code unless the change directly impacts it.
>
> **Existing feedback**: Other reviewers have already raised the points summarized below. Do not restate these — focus on issues not yet covered.

Where `pr_description` is the PR title + body concatenated.

Each agent returns standard JSON:
```json
{
  "summary": "One-sentence assessment",
  "score": 0-100,
  "findings": [{"severity": "critical|major|minor", "category": "...", "file": "...", "line": N, "finding": "...", "recommendation": "..."}],
  "verdict": "approve|request-changes"
}
```

## Step 6: Aggregate & Deduplicate

### 6a: Build Aggregation Table

```markdown
## PR Review — Multi-Agent Report

| Agent | Score | Verdict | Critical | Major | Minor |
|-------|-------|---------|----------|-------|-------|
| Code Quality | 85 | approve | 0 | 1 | 2 |
| Test Quality | 88 | approve | 0 | 1 | 0 |
| Security | 95 | approve | 0 | 0 | 1 |
| Performance | 82 | approve | 0 | 1 | 1 |
| Code Simplifier | 92 | approve | 0 | 0 | 2 |
| Housekeeper | 90 | approve | 0 | 1 | 0 |
| Architecture | -- | skipped | -- | -- | -- |
| Design | -- | skipped | -- | -- | -- |
| Conventions | 95 | approve | 0 | 0 | 1 |
```

### 6b: Deduplication Pass (LLM-driven)

Group all findings by file. For findings within **3 lines** of each other with semantically similar text:
- Merge into a single finding
- Keep the **higher severity**
- Attribute **all source agents** (e.g., "from: code-quality-reviewer, security-reviewer")
- Combine recommendations

If running in **incremental mode** (from Step 3a), also exclude findings that match previous groundwork review comments.

### 6c: Diff Mapping

Parse `pr_diff` to determine which finding lines fall within diff hunks. Use the `@@` hunk headers to map original/new line numbers.

- Findings whose `line` falls within a diff hunk on the RIGHT side → `inline_findings[]` (will be posted as inline review comments)
- Findings whose `line` falls outside any diff hunk → `general_findings[]` (will be included in review body)

## Step 7: Confirm with User

- **Non-interactive mode:** Log the summary below, then proceed directly to Step 8 (post review).
- **Interactive mode:** Show a preview via `AskUserQuestion`:

```json
{
  "questions": [{
    "question": "- **Inline comments**: [N]\n- **General findings**: [N]\n- **Verdict**: [APPROVE / REQUEST_CHANGES / COMMENT]\n- **Agents run**: [N] ([N] skipped)",
    "header": "PR Review Summary for [PR title] (#[pr_number])",
    "options": [
      { "label": "Post review" },
      { "label": "Show full preview", "description": "Display all findings before posting" },
      { "label": "Cancel" }
    ],
    "multiSelect": false
  }]
}
```

If "Show full preview" → display the full aggregation table plus all findings with their file/line/severity, then re-ask:

```json
{
  "questions": [{
    "question": "Review the findings above. Ready to post?",
    "header": "Post review?",
    "options": [
      { "label": "Post review" },
      { "label": "Cancel" }
    ],
    "multiSelect": false
  }]
}
```

If "Cancel" at either prompt → stop.

## Step 8: Post Review to GitHub

### 8a: Determine Review Event

- If ALL agents approved AND no critical or major findings → `event: APPROVE`
- If any agent returned `request-changes` OR any critical/major findings exist → `event: REQUEST_CHANGES`
- Otherwise → `event: COMMENT`

### 8b: Format Inline Comments

Each inline finding becomes a review comment:

```
**[severity]** [category] *(from: agent1, agent2)*

[finding]

**Recommendation:** [recommendation]
```

Map each to the GitHub review comment format:
- `path`: file path relative to repo root
- `line`: line number on the RIGHT side of the diff
- `side`: `RIGHT`

### 8c: Format Review Body

Build the review body:

```markdown
## Groundwork PR Review

[Aggregation table from 6a]

### General Findings

[List of general_findings not attached to inline comments]

---
*Reviewed by [N] agents | [N] findings ([N] inline, [N] general)*

```

The `` marker at the end enables future identification of groundwork-authored reviews.

### 8d: Post Atomic Review

Post a single review using the GitHub API to avoid multiple notifications. Use `--input -` with a single-quoted heredoc to pass the JSON payload via stdin — this avoids shell interpolation issues with complex markdown bodies.

**Do NOT** generate Python, Node, or any helper scripts to post the review. Use the `gh api --input -` approach below directly.

```bash
cat /pulls//reviews --method POST --input -
{
  "event": "",
  "body": "",
  "comments": [
    {
      "path": "src/example.ts",
      "line": 42,
      "side": "RIGHT",
      "body": "This condition doesn't handle the edge case where `input` is empty.\n\n```suggestion\nif (!input || input.length === 0) {\n  return defaultValue;\n}\n```"
    }
  ]
}
REVIEW_PAYLOAD
```

**JSON escaping rules** — inside the heredoc, the JSON must be valid:
- Escape double quotes as `\"`
- Escape newlines in string values as `\n`
- Escape backslashes as `\\`
- The single-quoted heredoc (`-review 2>/dev/null || true
   ```
3. Display final summary:
   ```markdown
   ## PR Review Posted

   **[PR title]** (#[pr_number]) — [url]

   - Event: [APPROVE / REQUEST_CHANGES / COMMENT]
   - Inline comments: [N]
   - General findings: [N]
   - Agents: [N] run, [N] skipped
   ```

## Key Design Notes

1. **Read-only**: Unlike validate, PR review does not fix issues — it only reports findings.
2. **Agent context adaptation**: Agents receive `pr_description` (PR title + body) instead of `task_definition`. They are prompted to focus on diff scope only.
3. **Deduplication is LLM-driven**: The orchestrating LLM compares findings by proximity and similarity — no external code needed.
4. **Diff position mapping**: Uses GitHub's `line` + `side=RIGHT` API. Parses diff hunk headers (`@@ -a,b +c,d @@`) to determine which lines are in scope.
5. **Atomic review posting**: Single API call posts both inline comments and summary, avoiding noisy multiple notifications.
6. **Groundwork marker**: `` HTML comment in review body enables identifying previous groundwork reviews for incremental mode.

## Severity Reference

| Level | Meaning |
|-------|---------|
| critical | Serious defect — security vulnerability, data loss, crash |
| major | Significant issue — logic error, missing edge case, poor design |
| minor | Improvement opportunity — style, naming, minor optimization |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [etr](https://github.com/etr)
- **Source:** [etr/groundwork](https://github.com/etr/groundwork)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-etr-groundwork-review-pr
- Seller: https://agentstack.voostack.com/s/etr
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.