Review Pr

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 ```

1. PR diff:

``bash gh pr diff ` Store as pr_diff`.

1. Changed file paths:

``bash gh pr view --json files --jq '.files[].path' ` Store as changedfilepaths`.

1. Diff stat:

``bash gh pr diff --stat ` Store as diff_stat`.

1. Existing reviews:

``bash gh api repos//pulls//reviews ` Store as existing_reviews`.

1. 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:

{
  "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

## 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:

{
  "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:

{
  "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:

## 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.

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

```

1. 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
• Source: etr/groundwork
• License: MIT

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