Review a GitHub pull request thoroughly — analyze diff for correctness, security, breaking changes, code quality, and AI-slop patterns. Supports --fix to auto-remediate findings and --reply to post the review back to GitHub via the gh CLI as a formal review.
Instrucciones de origen · Vista previa de solo lectura
name
ak:review-pr
description
Review a GitHub pull request thoroughly — analyze diff for correctness, security, breaking changes, code quality, and AI-slop patterns. Supports --fix to auto-remediate findings and --reply to post the review back to GitHub via the gh CLI as a formal review.
user-invocable
true
when_to_use
Invoke to review a GitHub PR by number/URL, optionally fix findings, optionally post the review back to GitHub.
API contract changes (request/response shapes, status codes)
Database schema changes without migrations
Config format changes without backwards compatibility
Removed or renamed exports/public interfaces
Code quality (anti-slop — terse checklist)
LLM-assisted PRs commonly introduce code that runs fine but pollutes the codebase. Scan the diff for these high-signal patterns:
New file in dumping-ground dirs (utils/, helpers/, lib/common/, *manager.ts) without a clear domain anchor
Parallel reimplementation of a utility that already exists in the repo (grep for prior art)
New abstraction (interface + factory + builder) with only one caller — premature
New config flag for behavior that should be hardcoded
Defensive paranoia — try/catch around code that cannot throw; null checks on typed-non-null params
File grows past the project's size limit (commonly 200 lines) without splitting
Diff size doesn't match scope ("fix typo" with +800/−60)
Touches files unrelated to stated purpose
Commit messages with generic LLM phrasing ("improve code quality and enhance maintainability")
Load the full taxonomy in references/anti-ai-slop.md when ANY of:
diff adds >300 lines, OR
≥2 inline anti-slop flags above fire, OR
PR creates >2 new files in utils//helpers//lib/common/, OR
you cannot confidently judge whether a pattern is genuine YAGNI vs slop
The reference covers: structural slop, micro slop, process slop, how to phrase the finding without becoming an AI-witch-hunt, when NOT to flag, and stack-specific appendix (Go, React/TS, Tailwind).
Project-specific compliance
Read the project's CLAUDE.md, AGENTS.md, docs/code-standards.md, docs/system-architecture.md if present
Check the diff against project conventions for: architecture patterns, ID scoping, SQL store rules, i18n catalogs, UI/CSS conventions, package manager, file-size limits
See references/project-rules-example.md for a worked example of project-specific compliance rules (Go gateway, React/Tailwind UI)
Testing
Are new code paths covered by tests?
Do existing tests still pass with these changes?
Are edge cases tested?
Watch for phantom coverage (assertions that always pass)
4. Summarize findings
Present your review as:
Summary: 1-2 sentence overview of what the PR does.
Risk level: Low / Medium / High — based on scope, complexity, and breakage potential.
Findings: List issues found, categorized by severity:
Critical: Must fix before merge (bugs, security, data loss)
Important: Should fix (logic issues, missing validation, structural AI slop)
Suggestion: Nice to have (style, minor improvements, micro AI slop)
Anti-slop severity rule: structural slop (new dumping-ground file, parallel reimpl, abstraction with one caller, schema change without migration, large file growth) → Important. Micro slop (over-comments, defensive paranoia, one-line wrappers) → Suggestion. This keeps --fix from churning the diff with cosmetic rewrites the original author won't recognize.
Verdict: One of:
Approve — No critical or important issues found
Request changes — Critical or important issues need addressing
Comment — Minor suggestions only, safe to merge as-is
Fix loop mode (--fix)
If $ARGUMENTS contains --fix, follow this loop after the review steps above:
1. Decide whether fixing is needed
If no actionable findings, stop and report Approve.
Actionable = all Critical + Important findings, plus Suggestion findings that are concrete, low-risk, and tied to PR scope.
Do not invent new style-only suggestions to keep the loop running.
2. Fix all findings
Activate ak:fix --auto with the full findings list and PR context:
ak:fix --auto "Fix all actionable findings from review-pr <PR_REF>: <finding summary>"
Pass the exact evidence:
PR reference, base branch, head branch
changed files
each finding: severity, file path, line/function, expected behavior, actual behavior, why it matters
constraints: preserve PR scope, avoid unrelated refactors, keep public contracts backward compatible unless the finding requires a contract change
ak:fix performs its own scout, diagnose, implementation, verification, and prevention flow. Do not bypass its hard gates.
3. Commit and push
After ak:fix verifies the fixes, activate:
ak:git cp
This stages, commits, and pushes the fixes to the PR head branch. Do not run ak:git cp if verification failed, secrets are detected, or the working tree contains unrelated user changes.
4. Re-review
After the push succeeds, activate review-pr <PR_REF> --fix again (carrying --reply if it was originally set) and repeat the loop.
Stop only when one of:
the re-review finds no actionable findings
ak:fix is blocked by a missing user/business decision
the same finding survives 3 consecutive fix attempts (loop not converging)
CI or local verification fails in a way ak:fix cannot resolve without user input
Final output for --fix mode:
iteration count
final verdict
commits pushed
remaining findings, if any
blockers or unresolved questions
Reply mode (--reply)
If $ARGUMENTS contains --reply, post the review back to GitHub as a formal review after the review (review-only) or after the fix loop converges (--fix).
1. Pre-flight checks
Run these checks. On any failure, fall back to printing the review locally and warn the user — never fail the whole skill:
Construct the full markdown body containing the summary, risk level, findings (by severity), and verdict. Append a single-line footer for traceability:
*Posted by the installed review-pr skill at <ISO-8601 UTC timestamp>*
Use date -u +"%Y-%m-%dT%H:%M:%SZ" for the timestamp.
Length cap: GitHub limits comment bodies to ~65,536 chars. If the body exceeds 60,000 chars, truncate the Findings section and append [truncated — N findings omitted; see local output] so the reviewer knows to consult the full chat output.
Pipe the body via stdin to avoid shell-quoting issues with backticks and code blocks.
4. Self-PR fallback
GitHub blocks approving your own PR. If gh pr review --approve exits non-zero with a self-review error (HTTP 422, message matching "Can not approve your own pull request"), retry as a neutral formal review:
gh pr review "$PR_REF" --comment --body-file -
The review still lands in the timeline; the verdict text inside the body still reads "Approve". Note the downgrade in the chat output.
5. Composition with --fix
In --fix --reply mode, post only the final re-review when the loop converges. Iteration history lives in the commit log; the PR conversation stays clean.
If the loop terminates due to a blocker (non-converging, ak:fix blocked, CI unresolvable), still post the final review — but the verdict will reflect remaining findings (likely Request changes or Comment), and the body should include the blocker so the human reviewer knows where to take over.
6. Idempotency
V1 does not dedupe. Re-running review-pr 123 --reply posts a fresh review each time. The traceability footer (step 2) is the seed for future dedup work but is not consumed here.
Final output
After all modes complete, report to the chat:
Verdict (Approve / Request changes / Comment)
Iteration count if --fix ran
Commits pushed if --fix ran
Whether --reply succeeded, fell back, or printed-locally
