PR Review Instructions

You are acting as a reviewer for a proposed code change. Your goal is to identify issues that could impact the quality, correctness, or safety of the codebase.

Read and follow all instructions in the co-located _review-core.md file (in this skill's directory) for the review methodology.

Arguments

Parse the ARGUMENTS environment variable (or skill arguments) for flags and the PR number:

--json — output structured JSON instead of Markdown (used for inline commenting in CI)
--devils-advocate — run an additional Devil's Advocate review pass after the standard review (see below)
--full — run all additional review passes: Devil's Advocate + JIRA Completeness verification (see below)
Remaining positional argument — the PR number

Examples: 123, --json 123, 123 --json, --devils-advocate 123, --full 123, --json --full 123

Note: --full implies --devils-advocate. You do not need to pass both.

Output Format

Default: Markdown

When --json is not specified, output the review directly to the terminal using this Markdown structure:

# PR Review: #{PR_NUMBER} - {PR_TITLE}

**PR:** {PR_URL}
**Author:** {AUTHOR} | **Base:** {BASE_BRANCH} ← **Head:** {HEAD_BRANCH}

## Summary

{1-2 sentence summary of what this PR does}

## Findings

### P0 - Critical

{List P0 issues, or "None" if empty}

-   **`{filepath}:{start_line}-{end_line}`** - {Issue title}
    {Short explanation of the issue and why it's critical}

### P1 - High

{List P1 issues, or "None" if empty}

-   **`{filepath}:{line}`** - {Issue title}
    {Short explanation}

### P2 - Medium

{List P2 issues, or "None" if empty}

-   **`{filepath}:{line}`** - {Issue title}
    {Short explanation}

---

_{N} low-priority issues omitted._

## Verdict

**Assessment:** {Patch is correct | Patch is incorrect}
**Confidence:** {0.0-1.0}

{Concise justification for the verdict - 1-2 sentences}

**Required Actions:** {Bulleted list of required fixes, or "None - ready to merge"}

JSON Mode (`--json`)

When --json is specified, output ONLY valid JSON. No markdown code fences, no explanatory text before or after. The output must be parseable by JSON.parse().

{
  "pr_number": 123,
  "pr_title": "Fix bug in chart rendering",
  "pr_url": "https://github.com/owner/repo/pull/123",
  "author": "username",
  "base_branch": "latest",
  "head_branch": "feature-branch",
  "commit_sha": "abc123def456...",
  "summary": "Brief 1-2 sentence summary of what this PR does",
  "findings": [
    {
      "priority": "P0",
      "file": "src/chart/series.ts",
      "line": 42,
      "end_line": 48,
      "title": "Issue title",
      "description": "Detailed explanation of the issue"
    }
  ],
  "verdict": {
    "assessment": "correct",
    "confidence": 0.85,
    "justification": "Brief reason for the verdict",
    "required_actions": ["Action 1", "Action 2"]
  },
  "stats": {
    "p0_count": 0,
    "p1_count": 1,
    "p2_count": 2,
    "p3_count": 3
  },
  "diff_stats": {
    "files_changed": 5,
    "lines_added": 150,
    "lines_removed": 20
  }
}

Field Definitions

Field	Type	Description
`pr_number`	number	The PR number
`pr_title`	string	The PR title
`pr_url`	string	Full URL to the PR
`author`	string	PR author's username
`base_branch`	string	Target branch (e.g., "latest")
`head_branch`	string	Source branch
`commit_sha`	string	Full SHA of the head commit (for inline comments)
`summary`	string	1-2 sentence summary of the PR
`findings`	array	List of issues found
`findings[].priority`	string	"P0", "P1", "P2", or "P3"
`findings[].file`	string	Relative file path from repo root
`findings[].line`	number	Line number in the NEW version of the file
`findings[].end_line`	number	Optional end line for multi-line issues
`findings[].title`	string	Short issue title
`findings[].description`	string	Detailed explanation
`verdict.assessment`	string	"correct" or "incorrect"
`verdict.confidence`	number	0.0 to 1.0
`verdict.justification`	string	Brief reason for verdict
`verdict.required_actions`	array	List of required fixes, or empty array
`stats`	object	Count of issues by priority
`diff_stats`	object	Statistics about the diff analyzed
`diff_stats.files_changed`	number	Number of files changed in the PR
`diff_stats.lines_added`	number	Number of lines added (+)
`diff_stats.lines_removed`	number	Number of lines removed (-)

Example JSON Output

{
  "pr_number": 5990,
  "pr_title": "Fix tooltip positioning in polar charts",
  "pr_url": "https://github.com/ag-grid/ag-charts/pull/5990",
  "author": "developer123",
  "base_branch": "latest",
  "head_branch": "fix/tooltip-polar",
  "commit_sha": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "summary": "Fixes tooltip positioning issues in polar charts by correctly calculating the angle-based offset.",
  "findings": [
    {
      "priority": "P1",
      "file": "packages/ag-charts-community/src/chart/tooltip/tooltip.ts",
      "line": 142,
      "end_line": 145,
      "title": "Missing null check for polar axis",
      "description": "The polarAxis could be undefined for non-polar series, which would cause a runtime error when accessing polarAxis.angle."
    },
    {
      "priority": "P2",
      "file": "packages/ag-charts-community/src/chart/tooltip/tooltip.ts",
      "line": 150,
      "title": "Magic number should be a constant",
      "description": "The offset value 15 should be extracted to a named constant for clarity and maintainability."
    }
  ],
  "verdict": {
    "assessment": "incorrect",
    "confidence": 0.85,
    "justification": "The fix addresses the main issue but introduces a potential null reference error that must be fixed before merge.",
    "required_actions": [
      "Add null check for polarAxis before accessing its properties"
    ]
  },
  "stats": {
    "p0_count": 0,
    "p1_count": 1,
    "p2_count": 1,
    "p3_count": 0
  },
  "diff_stats": {
    "files_changed": 2,
    "lines_added": 45,
    "lines_removed": 12
  }
}

Devil's Advocate Mode (`--devils-advocate`)

When the --devils-advocate flag is present, run an additional adversarial review pass after the standard review completes. This mode challenges assumptions, stress-tests edge cases, and questions whether the PR's approach is the right one.

Workflow

Run the standard review first. Complete the full review as described above and collect all findings.
Spawn a sub-agent with the Devil's Advocate instructions. Use the Agent tool to spawn a sub-agent with the following prompt structure:
- Include the full contents of agents/devils-advocate.md (co-located in this skill's directory) as the sub-agent's instructions.
- Pass the PR diff, PR metadata, and the --json flag state to the sub-agent so it has full context.
- The sub-agent should read and follow _review-core.md for shared methodology.
Merge findings from both passes.
- Combine standard review findings with Devil's Advocate findings (prefixed with [DA]).
- Deduplicate: if both passes flag the same file and line for the same issue, keep the higher-priority version and note it was flagged by both passes.
- In Markdown mode, add a ## Devil's Advocate Findings section after the standard ## Findings section.
- In JSON mode, merge the Devil's Advocate findings into the findings array (the [DA] prefix in the title distinguishes them).
Update the verdict. If the Devil's Advocate pass surfaces P0 or P1 issues not found in the standard review, adjust the verdict and confidence accordingly.

Full Review Mode (`--full`)

When --full is present, run all additional review passes in parallel after the standard review completes:

Devil's Advocate (as described above)
JIRA Completeness Verification (described below)
Code Simplification Review (described below)

All three sub-agents can be spawned simultaneously since they are independent of each other.

JIRA Completeness Verification

1. Extract JIRA IDs

Scan these sources (in order) for JIRA ticket references matching the pattern AG-\d+ or ST-\d+:

Branch name — e.g., ag-12345/fix-tooltip or ST-6789-update-utils
PR title and description — from gh pr view or $PR_TITLE
Commit messages — from git log of the PR's commits

Collect all unique ticket IDs found. The pattern match is case-insensitive (both ag-12345 and AG-12345 should match). Normalise to uppercase for the sub-agent (e.g., AG-12345).

2. Spawn the JIRA Completeness Sub-agent

Use the Agent tool to spawn a sub-agent with:

The full contents of agents/jira-completeness.md (co-located in this skill's directory) as instructions.
The extracted JIRA IDs.
A brief PR summary (from the standard review or PR metadata).
The list of changed files and diff stats.
The --json flag state.

3. Merge JIRA Findings

Combine JIRA findings (prefixed with [JIRA]) with the standard review and Devil's Advocate findings.
In Markdown mode, add a ## JIRA Completeness section after ## Devil's Advocate Findings (or after ## Findings if Devil's Advocate is not separately flagged).
In JSON mode, merge the JIRA findings into the findings array. Additionally, include the jira_summary object as a top-level field in the JSON output.
If no JIRA IDs were found at all, include a P1 finding noting the PR has no associated JIRA ticket.

4. Update the Verdict

If the JIRA verification reveals significant scope mismatches (PR does substantially different work than the ticket describes) or a missing JIRA link, factor this into the confidence score. JIRA hygiene findings alone (missing components, wrong status) should not change the code correctness verdict but should appear in required_actions.

Code Simplification Review

1. Spawn the Simplification Sub-agent

Use the Agent tool to spawn a sub-agent that performs the /simplify skill's analysis on the files changed by this PR. The sub-agent prompt should:

List the files changed in the PR (from git diff --name-only).
Instruct the agent to read those files and review the changed sections for opportunities to simplify — reuse existing utilities, reduce duplication, improve clarity, or eliminate unnecessary complexity.
Instruct the agent to report findings only, not make edits — this is a review, not an auto-fix.
Pass the --json flag state so output format matches.

The sub-agent should focus on the same concerns as the /simplify skill: reuse, quality, and efficiency. It should not flag style issues handled by linters or raise concerns about code it hasn't read.

2. Merge Simplification Findings

Combine simplification findings (prefixed with [SIMPLIFY]) with other findings.
In Markdown mode, add a ## Simplification Opportunities section after the JIRA section (or after whatever the last preceding section is).
In JSON mode, merge findings into the findings array with the [SIMPLIFY] title prefix.
Deduplicate against standard review findings — if the standard review already flagged the same issue (e.g., duplicated logic), keep the standard review version.

3. Verdict Impact

Simplification findings are advisory and should not change the code correctness verdict or confidence score. They appear as P2 or P3 suggestions in required_actions only if they represent genuine quality concerns (e.g., copy-pasted logic that should be extracted).

pr-review