---
name: code-review-pr-hygiene
description: "General-purpose PR hygiene review. Checks for cross-cutting issues that apply to any PR regardless of technology: secrets, unresolved placeholders, env/config parity across environments, URL list consistency, debug artifacts, and noisy/incomplete changes. Writes findings to _reviews/review.md with file paths and line numbers."
user-invocable: true
---

You are performing a PR hygiene review. Fetch the PR diff and evaluate it against the checklist below. Write your findings to `_reviews/review.md`, including the file path and line number for every finding. If the file already exists, overwrite it.

## Steps

1. Infer the PR number from the current branch name (e.g. `pr-1227` → PR `1227`). If unclear, use `gh pr view --json number` to find it.
2. Fetch the PR diff: `gh pr diff <PR_NUM> --repo <owner>/<repo>`
3. Read relevant local source files as needed using the Read, Grep, and Glob tools to get accurate line numbers.
4. Evaluate each item in the checklist below.
5. Write findings to `_reviews/##.md` using the format described at the bottom of this document. Where `##` is the PR number.

**Important**: Do not run arbitrary build or test commands. Use `gh`, Read, Grep, and Glob tools only.

## Review Checklist

### 🔴 Secrets & Credentials
- Are any secrets, API keys, tokens, or passwords hardcoded in the diff? Flag immediately.
- Are placeholder patterns (e.g. `##SOME_VAR##`, `{{VAR}}`, `<REPLACE_ME>`) present in files that should have real values at runtime?

### 🟡 Debug & Temporary Artifacts
- Are there leftover `console.log`, `print`, `debugger`, or `TODO`/`FIXME` comments introduced by this PR?
- Are commented-out code blocks added (not pre-existing)?

### 🟡 Whitespace & Noise
- Are there whitespace-only changes (blank lines, trailing spaces) unrelated to the functional change?
- Are formatting-only changes mixed in with logic changes, making the diff harder to review?

### 🟢 Completeness
- Does the PR description match the actual diff? Are there changes present that aren't mentioned, or claims that aren't reflected in the diff?
- If new infrastructure is added (client, API, service), is it registered/wired up everywhere it needs to be (e.g. connection enabled_clients, service discovery, routing)?
- Are related documentation files (README, changelogs, runbooks) updated if the change affects them?

### 🟢 Unit tests
- If the PR includes new functionality, are there corresponding unit tests added?
- If the PR includes bug fixes, are there corresponding unit tests added that would have failed before the fix?
- Do the tests cover edge cases and potential failure modes, or just the happy path?
- Verify that the tests include mocks/stubs for any external dependencies, and that they assert on the expected interactions with those dependencies.

## Output Format

Write findings to `_reviews/review.md` using this structure:

```markdown
# PR Hygiene Review: <PR title> (#<number>)

## 🚫 Blockers
> These must be resolved before the PR can be merged.

1. **<Short title>**
   `<file path>` line <N>: <Description of the issue and why it matters.>

   ```<lang>
   // Suggested change
   <code snippet showing the fix>
   ```

## 💬 Nits
> Minor issues that can be addressed in a follow-up PR.

1. **<Short title>**
   `<file path>` line <N>: <Description of the issue.>

   ```<lang>
   // Suggested change
   <code snippet showing the fix>
   ```

## ✅ No issues found in these areas
- <List checklist categories that were clean>
```

**Blocker vs. Nit guidance:**
- **Blocker**: Secrets/credentials, unresolved placeholders, missing wiring for new infrastructure, test coverage gaps for new/fixed behavior.
- **Nit**: Debug artifacts, whitespace noise, minor documentation gaps, style inconsistencies, TODOs that don't block correctness.

**Code snippet guidance:** For every finding, include a suggested code snippet showing the recommended fix. Use the actual file content as context so the snippet is copy-paste ready. If no code change is needed (e.g. a missing file must be created), describe what to add instead.

If there are no findings in a section, omit that section. Always include the "No issues found" section for clean areas.