Pr Review Recommender

PR Review Recommender

Overview

Use this skill to perform a comprehensive pull request review and end with an explicit, justified merge recommendation. Keep the review evidence-based: cite commit signature status, PR template checklist status, changed files, test results, CI status, and any assumptions or limitations.

Review Workflow

1. Verify commit signing before reviewing code.

   • IMPORTANT: all commits in the PR must be signed.
   • Check every PR commit's signature verification status before inspecting the diff.
   • If any commit is unsigned, unverified, has an unknown verification state, or commit verification cannot be checked, stop the review immediately.
   • When stopping, do not continue into correctness, security, tests, maintainability, or merge-readiness review.
   • Tell the contributor which commit(s) are not signed or could not be verified, recommend Do not merge yet, and provide signing guidance with these GitHub documentation links:
     • About commit signature verification
     • Signing commits
     • Telling Git about your signing key

2. Verify the PR template checklist.

   • Find the repository's PULL_REQUEST_TEMPLATE.md or configured pull request template and compare its required checks with the PR description.
   • Make sure all checks in PULL_REQUEST_TEMPLATE.md are addressed.
   • Treat unchecked boxes, omitted required checklist items, or vague placeholders as unresolved unless the contributor clearly explains why an item does not apply.
   • If required checklist items are not addressed, record a Blocker finding and recommend Do not merge yet. Continue the code review only when enough information remains to review the implementation responsibly.

3. Establish the PR intent.

   • Read the PR description, linked issue, commit messages, and changed-file summary.
   • Identify the promised behavior change, user impact, compatibility expectations, and out-of-scope work.
   • Flag mismatches between the stated intent and implementation.

4. Inspect the diff for correctness.

   • Review changed code paths, affected callers, defaults, error handling, edge cases, and backward compatibility.
   • Look for incomplete refactors, dead code, duplicated logic, concurrency issues, async mistakes, and surprising behavior changes.
   • Trace user-facing flows instead of only reading isolated hunks.

5. Review security and data-safety implications.

   • Check for exposed secrets, unsafe logging, weak authz/authn, injection, shell execution, path traversal, SSRF, unsafe deserialization, and dependency risk.
   • Verify user-controlled input is validated and errors are safe.
   • Treat security-sensitive behavior changes as requiring stronger tests and clearer justification.

6. Review tests and validation evidence.

   • Confirm tests cover the happy path, meaningful edge cases, regression cases, and failure modes.
   • Prefer tests that would fail without the PR.
   • If tests cannot be run, state that explicitly and include the resulting risk in the recommendation.

7. Review maintainability.

   • Evaluate naming, structure, type usage, duplication, public API docs, function size, and consistency with local style.
   • Prefer focused PRs; flag unrelated rewrites or changes that make future maintenance harder.

8. Review dependencies, packaging, migrations, and docs when relevant.

   • For dependency changes, check necessity, version constraints, license/maintenance signals, and lockfile consistency.
   • For behavior changes, check user docs, CLI/API help, migration notes, release notes, screenshots, or examples.

9. Classify findings by severity.

   • Blocker: must fix before merge; examples include unsigned/unverified PR commits, unaddressed required PR template checks, security issues, data loss, broken core behavior, failing required tests, or incomplete implementation.
   • Major: should usually fix before merge; examples include missing important tests, likely user-facing edge-case bugs, or poor error handling in important paths.
   • Minor: can be fixed before or shortly after merge; examples include small documentation, naming, or cleanup issues.
   • Nit: optional polish.

10. Make a merge recommendation.

• Use exactly one of: Merge, Merge after minor changes, Do not merge yet, or Request redesign.
• Justify the recommendation using the highest-severity unresolved findings, test evidence, and risk assessment.

Output Template

## Summary

Briefly describe what the PR changes and whether the implementation matches the stated intent.

## Review scope

Files/areas reviewed:
- `path/to/file`


Evidence checked:
- Commit signatures reviewed
- PR template checklist reviewed
- Diff inspection
- Tests reviewed
- CI status reviewed
- Local commands run, if any

## Findings

### <Severity>: <Short finding title>

Explain the issue, impact, and why it matters.

Suggested fix:
Describe the concrete fix or mitigation.

For unsigned or unverified commits, tell the contributor to rewrite or squash the PR commits with signing enabled and force-push the branch after confirming the rewritten commits show as verified on GitHub. Include the GitHub documentation links listed in the workflow.

For unaddressed PR template checks, list the missing or unchecked item(s), ask the contributor to update the PR description or complete the required work, and recommend **Do not merge yet** until the checklist is addressed.

## Positive notes

- Mention well-designed, well-tested, or low-risk parts of the PR.

## Test evidence

- `<command or CI check>`: pass/fail/not run, with reason when not run.

## Merge recommendation

**Recommendation: <Merge | Merge after minor changes | Do not merge yet | Request redesign>.**

Justification:
Explain the decision in terms of correctness, risk, tests, and unresolved findings.

Recommendation Rules

• Recommend Merge only when all PR commits are signed and verified, all required PR template checks are addressed, implementation is correct, risk is low, and no blocker or major findings remain.
• Recommend Merge after minor changes when the PR is sound and only minor/nit issues remain.
• Recommend Do not merge yet when any PR commit is unsigned, unverified, or cannot be checked; when required PR template checks are not addressed; when blockers or major issues remain; when required tests are missing; or when validation is insufficient for the risk level.
• Recommend Request redesign when the approach is fundamentally misaligned, too broad, or likely to create long-term architectural or maintenance problems.

Review Tone

Be direct, specific, and actionable. Avoid vague comments such as “this seems wrong”; explain the impact and propose a fix. Separate facts from assumptions. If evidence is unavailable, say what was not checked and how that affects confidence.