---
description: Review a GitHub PR for methodology, code quality, and maintainability
argument-hint: "<PR-number> [--paper <path>] [--post]"
---

# Review Pull Request

Perform comprehensive code review on a GitHub PR.

## Arguments

`$ARGUMENTS` should contain:
- PR number (required): e.g., "74", "#74"
- `--paper <path>` (optional): Path to reference paper (PDF) for methodology validation
- `--post` flag (optional): Post the review instead of generating draft

## Modes

### Draft Mode (default)
`/review-pr <number>` - Generate review and save to file

### Post Mode
`/review-pr <number> --post` - Post existing review to PR

## Review Framework

Analyze PRs across 6 dimensions:

### 1. Methodology Review
- Statistical/algorithmic correctness
- Alignment with academic references (if `--paper` provided, compare implementation against paper)
- Edge case handling
- Mathematical accuracy of formulas/algorithms

### 2. Code Quality
- Test coverage for new code
- Error handling
- API consistency with existing codebase patterns

### 3. Security Review
- Input validation and sanitization
- Injection risks (SQL, command, etc.)
- Secrets/credentials exposure
- Dependency vulnerabilities

### 4. Documentation Review
- Docstrings for new/modified functions
- `diff_diff/guides/llms.txt` updated if a new public-API surface landed (AI-agent contract)
- API documentation (RST files in `docs/api/`)
- `docs/references.rst` updated for new scholarly citations
- README updated ONLY for landing-page-relevant changes (catalog one-liner, hero/badges/tagline, top-level capability paragraph). Per CONTRIBUTING.md, README is not the place for usage examples or per-estimator sections.
- Inline comments for complex logic

### 5. Performance
- Computational complexity
- Memory usage
- Unnecessary operations

### 6. Maintainability & Tech Debt
- Code duplication
- Breaking changes
- Backward compatibility

## Instructions

### 1. Parse Arguments

Parse `$ARGUMENTS` to extract:
- **PR number**: Required. Strip '#' prefix if present.
- **--paper <path>**: Optional. Path to reference paper PDF for methodology validation.
- **--post**: Optional flag. If present, post the review instead of generating draft.

If no PR number is provided, use AskUserQuestion to request it.

### 2. Draft Mode Workflow (default, when --post is NOT present)

1. **Fetch PR info** using GitHub MCP tools:
   - Use `mcp__github__get_pull_request` to get PR details (title, description, author, base branch)
   - Use `mcp__github__get_pull_request_files` to get list of changed files

2. **Analyze changes**:
   - Read each changed file using the Read tool to understand the full context
   - For source files (.py): Review methodology correctness, code quality, security
   - For test files: Assess test coverage completeness for new functionality
   - For documentation files: Check accuracy and completeness
   - **If `--paper` was provided**:
     - Read the PDF using the Read tool
     - Compare implementation against algorithms/formulas in the paper
     - Note any deviations, simplifications, or potential errors

3. **Generate review** following this template structure:

```markdown
# Code Review: PR #[number] - [title]

**Author**: [author]
**Branch**: [head] -> [base]
**Files Changed**: [count]

---

## Executive Summary

[2-3 sentences describing what the PR does and your overall assessment]

---

## Part 1: Methodology Review

[For PRs with statistical/algorithmic changes, assess correctness]
[If --paper was used, include comparison against the reference paper]
[If not applicable, write "N/A - No methodology changes in this PR"]

---

## Part 2: Issues Found

### Critical Issues
[Must fix before merge - security vulnerabilities, bugs, incorrect algorithms]

### Medium Issues
[Should fix - code quality, missing tests, documentation gaps]

### Minor Issues
[Nice to have - style suggestions, minor optimizations]

---

## Part 3: Security Assessment

[Assessment of security concerns, input validation, etc.]
[If no security concerns, note "No security issues identified"]

---

## Part 4: Documentation Assessment

[Check docstrings, llms.txt for new public-API surfaces, API RST docs, references.rst for new citations, README only for landing-page-relevant changes]

---

## Part 5: Performance Assessment

[Computational complexity, memory usage, potential bottlenecks]

---

## Part 6: Maintainability Assessment

[Code duplication, backward compatibility, tech debt]

---

## Recommendations

### Must Fix (before merge)
1. [item]

### Should Fix
1. [item]

### Nice to Have
1. [item]

---

## Final Assessment

| Category | Rating | Notes |
|----------|--------|-------|
| Methodology | [icon] | [brief note] |
| Code Quality | [icon] | [brief note] |
| Security | [icon] | [brief note] |
| Documentation | [icon] | [brief note] |
| Performance | [icon] | [brief note] |
| Maintainability | [icon] | [brief note] |

**Overall Verdict**: [Approved / Approved with Minor Changes / Needs Revision / Needs Major Revision]

---

*Review generated by Claude Code*
```

Use these rating icons:
- Pass/Good: checkmark
- Warning/Minor issues: warning sign
- Fail/Major issues: X mark

4. **Save the review**:
   - Create `.claude/reviews/` directory if it doesn't exist (use Bash: `mkdir -p .claude/reviews`)
   - Write the review to `.claude/reviews/pr-{number}-review.md` using the Write tool
   - Overwrite any existing file (no confirmation needed)

5. **Report to user**:
   - Show a summary of what was found
   - Tell them the file path
   - Instruct them to edit the file if needed, then run `/review-pr <number> --post`

### 3. Post Mode Workflow (when --post IS present)

1. **Check for draft file**:
   - Try to read `.claude/reviews/pr-{number}-review.md`
   - If file doesn't exist, tell user to run without --post first to generate the draft

2. **Post to PR**:
   - Use `mcp__github__add_issue_comment` to post the review content
   - The owner and repo should be determined from the current git repository (use `git remote get-url origin` and parse it)

3. **Confirm success**:
   - Tell user the review was posted
   - Provide the PR URL

## Output Examples

### Draft Mode Output
```
Review generated for PR #74

Draft saved to: .claude/reviews/pr-74-review.md

Summary:
- 5 files changed (3 source, 1 test, 1 docs)
- Found 1 critical issue, 2 medium issues, 1 suggestion
- Methodology: Correct
- Overall: Needs Revision

Edit the review file as needed, then run:
  /review-pr 74 --post
```

### Post Mode Output
```
Review posted to PR #74
https://github.com/owner/repo/pull/74
```

### Error Output (no draft exists)
```
No review draft found for PR #74

Run without --post first to generate the draft:
  /review-pr 74
```

## Notes

- Reviews are saved as markdown files for easy editing before posting
- The --post flag reads from the saved file, preserving any user edits
- Draft mode always overwrites any existing draft for that PR number
- The skill only reviews PRs from the current repository (no cross-repo support)
- For methodology validation, the --paper flag accepts PDF files which Claude can read directly
