review-pr

# Review Pull Request

Parse `$ARGUMENTS` to extract the PR identifier and optional reviewer instructions:
- Everything before the first `--` (or all of it, if there is no `--`) is the **PR identifier** (URL or number). Referred to as `PR_ID` below.
- Everything after the first `--` is **reviewer instructions** — additional focus areas or context from the caller. If absent, there are no special instructions.

Analyze the pull request: PR_ID

## Steps

Run the following steps. Gather data in parallel where possible.

### 1. Set up worktree

Resolve the PR number:

```
gh pr view PR_ID --json number
```

Use the number to form the worktree name `review-pr-<number>`.

Invoke the `/create-worktree review-pr-<number> --pr <number>` skill to create an isolated worktree for this PR. Note the worktree path from the skill output — referred to as `WORKTREE` below.

Verify that the cwd is now inside the worktree:

```
pwd
```

If `pwd` does not show `WORKTREE`, run `cd WORKTREE` and verify again. Stop with an error if the cwd cannot be set. Once confirmed, subsequent Bash calls will run inside the worktree automatically.

### 2. Fetch PR metadata and diff

Use `gh` to collect all PR information in parallel:

- `gh pr view PR_ID --json title,body,author,state,baseRefName,headRefName,number,url,comments,reviews,labels,milestone`
- `gh pr diff PR_ID`

### 3. Check dependency changes in `pyproject.toml`

If the PR diff (from step 2) touches `pyproject.toml`, run the automated dependency checker.

First, fetch the latest `devel` from origin so the comparison is against the current state:

```
git fetch origin devel
```

Then run the script — always compare against `origin/devel` regardless of the PR's base branch:

```
python tools/check_dependency_changes.py origin/devel
```

The script finds the merge-base, simulates a three-way merge (like GitHub), and reports:
- **Main dependencies** (`[project.dependencies]`) — displayed as WARNING (these affect every user)
- **Optional dependencies** (`[project.optional-dependencies]`) — displayed as WARNING (these affect users of specific extras)
- **Dev/group dependencies** (`[dependency-groups]`) — listed for awareness (no impact on end users)
- **Merge conflicts** — if `pyproject.toml` would conflict, the script warns and falls back to showing the PR's intended changes

Include the script output verbatim in the review. If the script exits with code 1 (changes detected), flag dependency changes in the review verdict. If it exits with code 2 (conflicts), flag that `pyproject.toml` needs conflict resolution.

If `pyproject.toml` is not in the diff, skip this step.

### 4. Check CI lint and mypy status

Use `gh pr checks PR_ID` to retrieve the CI check results. Look for checks matching `lint on all python versions / lint*` — these run mypy, ruff, flake8, bandit, and docstring checks across Python 3.9–3.13 (defined in `.github/workflows/lint.yml`).

- Report the status of each lint check (pass/fail/pending).
- If any lint check has failed, fetch its logs with `gh run view <run-id> --log-failed` to identify the specific errors (mypy type errors, ruff violations, etc.).
- Include lint/mypy status in the final review verdict. A failing lint check should be flagged as a required fix.

### 5. Analyze related issues

Extract any issue references from the PR body (e.g. `fixes #1234`, `closes #1234`, `#1234`). For each referenced issue, fetch it with:

- `gh issue view <number> --json title,body,author,state,comments,labels`

Understand the original problem being solved.

### 6. Analyze the code

Using absolute paths under `WORKTREE`:

- Read the changed files in full to understand context beyond the diff.
- Look at callers/callees of modified functions.
- Check if similar patterns exist elsewhere that should also be updated.
- Review the coding style and code patterns to conform with @CLAUDE.md
- If **reviewer instructions** were provided, pay special attention to the areas or concerns they describe during this analysis.
- Mention only crucial finding to the user in the initial overview. Avoid code snippets except if critical bugs were found

### 7. Review test coverage

#### 7a. Define the testing scope

Based on the PR changes, identify what needs to be tested:

- What are the distinct behaviors introduced or modified?
- What are the edge cases and error paths?
- What are the integration boundaries (e.g., does the change affect how components interact)?

Produce a checklist of required test scenarios before evaluating existing tests.

#### 7b. Evaluate existing tests against the checklist

- Compare the PR's tests against the required scenarios checklist. Flag any gaps.
- Flag any tests that verify things outside the PR's scope or test obvious/trivial behavior that adds no value.

#### 7c. Verify tests are in the right modules

- Search the test directory for where similar functionality is already tested (grep for related function names, class names, or feature keywords).
- New tests should live alongside related existing tests, not in new files unless the PR introduces an entirely new module.
- Flag tests placed in the wrong location.

#### 7d. Check for duplication and over-testing

- Look for tests that cover nearly identical cases and could be merged or parametrized with `@pytest.mark.parametrize`.
- Look for repeated setup/assertion logic across tests that should be extracted into a helper or fixture.
- If multiple tests differ only in a single variable (e.g., `True`/`False`, different type values), they must be parametrized into one test function.
- Flag any copy-paste test code. Minimizing test code maintenance burden is a priority.

#### 7e. Bug Fixes Should Have Regression Tests
If the PR fixes a bug:
- Is there a test that would have caught the bug before the fix?
- Does the test verify the specific scenario from the bug report?

### 8. Check documentation coverage

If the PR modifies public API (new parameters, changed behavior, new configuration options, new functions/classes exposed to users):

- Search `WORKTREE/docs/website/docs/` for existing documentation covering the topic of the PR.
- If the topic is already documented and the PR changes its behavior or adds new options, verify that the PR also updates the relevant doc pages.
- If documentation updates are missing, flag this in the review as a required change.
- If the topic is not documented at all, this is not a blocker — don't require docs for previously undocumented internals.

### 9. Produce the review

Write a structured analysis covering:

- **Summary**: What the PR does and why, referencing the linked issue.
- **Changes**: Breakdown of changes should be concise, avoid code samples
- **Dependency Changes**: If `pyproject.toml` was modified, include the warnings and listings from step 3. Main and optional dependency changes must appear as yellow WARNING blocks. Omit this section if no dependency changes were found.
- **CI Lint & Mypy**: Status of lint checks across Python versions. If any failed, list the specific errors.
- **Observations & Potential Issues**: Bugs, edge cases, missing error handling, performance concerns, memory issues, security issues, backward compatibility.
- **Breaking Changes and Public API**: Follow the rules on breaking changes and Public API and report issues.
- **Test Coverage**: Required scenarios checklist with pass/fail status, misplaced tests, duplication issues, parametrization opportunities.
- **Documentation**: Whether doc updates are needed and if they were provided.
- **Reviewer Instructions**: If reviewer instructions were provided, include a dedicated section addressing each point raised. If no instructions were provided, omit this section.
- **Verdict**: Overall assessment.