Pr Review

Comprehensive Code Review

Perform a thorough code review of all Git changes (both staged and unstaged) with security, performance, and quality analysis.

Focus Area: $ARGUMENTS (if provided, emphasize this area in the review)

Submission Invariant (read this first)

If the review is going to be posted to GitHub, you MUST route the submission through $SKILL_DIR/scripts/submit-pr-review.ts. This is the only sanctioned path. The script builds a proper GitHub review with inline comments anchored to the PR's right-hand hunks; bypassing it produces a single prose comment that nobody reads as a review.

Never use any of these shortcuts, even "just this once":

• gh pr review --body / gh pr review --body-file
• gh pr comment
• gh api -X POST /repos/.../pulls//reviews with a handcrafted body
• Writing the review to a tempfile and piping it through gh
• Dispatching a sub-agent to "just post this"

If you find yourself writing markdown headers like "## Code Review" into a tempfile and then reaching for gh, stop — you have left the sanctioned path. The script is the path.

Additional rules the script enforces at runtime:

• Abort on critical drop. If a finding with severity: "critical" anchors to a line outside the PR diff, the script aborts instead of silently dropping it. Re-anchor, downgrade, or remove — do not ignore.
• Abort on a moved head. With --expect-head , the script refuses to post when the PR's current head differs from the revision the review was written against. Re-read the new diff and re-verify every anchor before resubmitting.
• Non-critical drops are named, not just counted. Any finding that fails to anchor is printed to stderr as id file:line title, in both dry-run and submit mode. Read that list; a drop means the finding was never delivered.
• No methodology chrome. The script rejects review text that mentions the parallel reviewers, synthesis, corroboration, contested findings, or confidence tags. The PR review must read as if a human wrote it. "Reviewed with Opus + Codex second-opinion validation." and "(codex confirmed)" are disallowed. Rewrite into plain review prose.

Output Audience

This skill has two invocation paths, and the output differs for each. Pick the right one before writing a single character of output.

| Invocation | Audience | Output format | | ----------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | User runs /pr-review directly | Human | Markdown only. Follow the "Output Format" section below (Executive Summary, Critical Issues, etc.). Do not print the JSON finding array. | | code-reviewer agent dispatches a reviewer sub-agent | Orchestrator agent | JSON array per [references/finding-schema.md](references/finding-schema.md), for programmatic synthesis. |

If you are uncertain which path you are on, you are on the user-facing path: emit markdown, never JSON.

Step 0a: Resolve PR Context

Before the local-diff pipeline runs, determine whether this invocation is scoped to a GitHub pull request. PR mode changes the diff source and enables the optional submission flow in Step 9.

1. If $ARGUMENTS is a PR number (e.g., 123) or a PR URL (e.g., https://github.com/acme/widgets/pull/123), resolve with:

``bash gh pr view --json number,headRepository,baseRefName,author,headRefName,headRefOid,url ``

Capture pr_number, owner (from headRepository.owner.login), repo (from headRepository.name), pr_author (from author.login), pr_url, and head_sha (from headRefOid). Set pr_mode = true.

head_sha matters. It pins the revision this review is written against. A PR can be force-pushed while you are still reading the diff, and every line anchor you computed then belongs to a revision that no longer exists. Step 9 passes this value back to the submission script, which refuses to post if the PR has moved.

1. Else, try resolving from the current branch:

``bash gh pr view --json number,headRepository,baseRefName,author,headRefName,headRefOid,url ``

If the command succeeds and returns a PR, capture the same fields and set pr_mode = true.

1. Else, set pr_mode = false and proceed with today's working-tree flow.

Failure mode: if $ARGUMENTS clearly intends PR mode (a PR reference was supplied) but the gh pr view lookup fails, abort with a clear error. Do not silently fall through to working-tree mode.

Step 0: Repository Health Context

Before examining the diff, build a risk profile of the repository. These five commands surface files and patterns that deserve extra scrutiny during the review. Run all five.

# 1. High-churn files (20 most-changed in the last year)
#    Frequently changed files signal maintenance hotspots and defect clusters.
git log --format=format: --name-only --since="1 year ago" | sort | uniq -c | sort -nr | head -20

# 2. Team structure & bus factor
#    Reveals knowledge concentration and active vs historical maintainers.
git shortlog -sn --no-merges

# 3. Bug hotspots (files recurring in fix/bug/broken commits)
#    Maps the areas that get repeatedly patched.
git log -i -E --grep="fix|bug|broken" --name-only --format='' | sort | uniq -c | sort -nr | head -20

# 4. Project momentum (monthly commit frequency)
#    Exposes velocity patterns and team transitions.
git log --format='%ad' --date=format:'%Y-%m' | sort | uniq -c

# 5. Crisis patterns (reverts, hotfixes, emergencies, rollbacks in the last year)
#    Indicates deployment confidence and process reliability.
git log --oneline --since="1 year ago" | grep -iE 'revert|hotfix|emergency|rollback'

Cross-reference for risk assessment (critical step):

After Step 1 produces the list of changed files, check each one against the outputs above:

• Changed file appears in #1 (high-churn) -> raise review severity by one level; the file has a history of instability.
• Changed file appears in #3 (bug hotspots) -> treat as high-risk; scrutinize error handling, edge cases, and test coverage aggressively.
• Changed file is owned by a single contributor per #2 -> flag bus-factor risk in the review summary.
• Recent crisis activity per #5 touches related areas -> call out in the Executive Summary and question whether this change could reintroduce or compound a prior incident.

Record the risk profile before proceeding so it informs every subsequent section. Source: Piechowski, "Git Commands Before Reading Code" (https://piechowski.io/post/git-commands-before-reading-code/).

Step 1: Gather Context

When pr_mode == true, the review diff is the PR's own diff:

gh pr diff 

Note: this is the diff shown on github.com for the PR. Uncommitted local edits to a checked-out PR branch are not included; if the user wants those reviewed, they should run /pr-review without a PR argument on a branch with no associated PR.

When pr_mode == false, analyze the current Git state:

git status                    # Current state
git diff --cached --stat      # Staged changes summary
git diff --stat               # Unstaged changes summary
git log -5 --oneline          # Recent commits for context

Then read the actual diffs:

git diff --cached             # Full staged diff
git diff                      # Full unstaged diff

Review Sections

1. Git Changes Analysis

• Examine all modified, added, and deleted files
• Review the scope and nature of changes
• Check for large file modifications that might need special attention
• Identify files that may have unintended changes

2. Code Quality Review

| Area | What to Check | | ----------------------- | --------------------------------------- | | Style & Conventions | Adherence to project coding standards | | Complexity | Overly complex functions or classes | | Pattern Consistency | Consistent architectural patterns | | Dead Code | Unused variables, functions, or imports | | DRY Violations | Code duplication opportunities | | Naming | Variable, function, and class naming | | Organization | File structure and module organization |

3. Security Review

| Area | What to Check | | -------------------- | ---------------------------------------------- | | Secrets | Hardcoded credentials, API keys, passwords | | Input Validation | Proper sanitization of user inputs | | SQL Injection | Database queries for injection vulnerabilities | | XSS Prevention | Proper output escaping in web contexts | | Auth/AuthZ | Access control implementations | | Dependencies | Potentially vulnerable dependencies | | Data Exposure | Sensitive data logging or exposure |

4. Performance Analysis

| Area | What to Check | | -------------- | ------------------------------------------------- | | Algorithms | Inefficient algorithms or data structures | | Database | N+1 queries, missing indexes, inefficient queries | | Memory | Potential memory leaks or excessive allocations | | Frontend | Unnecessary re-renders, large bundle sizes | | Caching | Areas that could benefit from caching | | Async | Proper use of asynchronous patterns |

5. Error Handling & Reliability

| Area | What to Check | | --------------- | -------------------------------- | | Exceptions | Proper try/catch implementations | | Propagation | Error handling strategies | | Degradation | Graceful failure handling | | Logging | Logging levels and completeness | | Validation | Comprehensive input validation |

6. Testing Considerations

| Area | What to Check | | ---------------- | ---------------------------------- | | Coverage | New functionality that needs tests | | Edge Cases | Edge cases that should be tested | | Test Quality | Existing test modifications | | Integration | Integration points needing tests | | Mocks | Proper use of test doubles |

7. Documentation Review

| Area | What to Check | | -------------- | --------------------------------------- | | Comments | Missing or outdated comments | | Docstrings | Function documentation and parameters | | API Docs | Updated API documentation needs | | README | Changes requiring documentation updates |

8. Best Practices Compliance

| Area | What to Check | | --------------- | -------------------------------------------- | | SOLID | Adherence to design principles | | Patterns | Appropriate use of design patterns | | Separation | Proper separation of concerns | | Config | Hardcoded values that should be configurable | | Environment | Environment-specific code handling |

Output Format

Provide a structured review with these sections:

Executive Summary

High-level overview of changes and overall assessment.

Critical Issues (Must Fix)

Security vulnerabilities, bugs, breaking changes.

High Priority

Important improvements for performance and maintainability.

Medium Priority

Good-to-have improvements for code quality and conventions.

Low Priority

Minor suggestions for style and optimizations.

Positive Highlights

Well-implemented aspects worth noting.

Action Items

Specific, actionable recommendations.

Issue Format

For each issue, include:

**[SEVERITY] Issue Title**

- **File**: path/to/file.ts:123
- **Problem**: Clear description of the issue
- **Suggestion**: How to fix it
- **Impact**: Risk level (Critical/High/Medium/Low)

Guidelines

• Be thorough but constructive
• Prioritize issues by impact
• Provide specific line references where applicable
• Suggest solutions, not just problems
• Acknowledge good practices

Step 9: PR Submission (conditional)

Runs only if all three conditions hold:

1. pr_mode == true (resolved in Step 0a).
2. The current GitHub user is not the PR author:

``bash gh api user --jq .login ``

Compare to pr_author from Step 0a. If equal, skip Step 9 entirely. No prompt, no submission. The markdown report is the final output.

1. The review produced at least one finding.

When all three hold, drive this flow:

1. Resolve the attribution values before assembling the review:

• agent_name: the current executing agent's display name, such as Codex or Claude.
• human_name: run gh api user --jq '.name // .login' and use its output.

The submission script appends this footer to the review body and every inline comment:

```markdown ###### Sent from

• [ ] reviewed by

```

Do not add the footer to the findings file yourself. Pass the resolved values to the submission script with --agent-name and --human-name.

1. Assemble a review document and write it to a tempfile using Write:

``json { "summary": "", "findings": [, ...] } ``

Findings match the shape in references/finding-schema.md. Only description plus the generated footer is posted inline to the PR; the other fields are orchestrator bookkeeping. Inline any code reference the reader needs directly into description (backticks or fenced blocks) — there is no separate evidence block. Strip orchestrator-internal fields (sources, contested, synthesisNote) before writing. Do not mention the review methodology (no "Opus", "Codex", "corroborated", "contested", "synthesis", "second-opinion", "(codex confirmed)", "reviewed with..."). The script rejects these tokens; if your text hits them, rewrite to plain review prose.

Keep summary short or empty. It becomes the review body (before the generated footer, with no ## Code review heading). One or two sentences max, and only when you have something meaningful to add on top of the inline comments. When there's nothing to add, pass ""; the required footer still appears in the review body.

1. Invoke the submission script with --dry-run to preview the payload:

``bash bun $SKILL_DIR/scripts/submit-pr-review.ts \ --pr \ --owner --repo \ --findings \ --agent-name \ --human-name \ --expect-head \ --dry-run ``

Pass --expect-head with the head_sha captured in Step 0a. Omitting it is only acceptable when no head_sha was resolved.

Parse the JSON on stdout. Fields: payload (the assembled review), head_sha (the revision the script fetched and anchored against), counters ({ inline, dropped, critical_dropped }), dropped (every finding that failed to anchor), critical_dropped (the subset of those that are critical).

1. Moved-head abort. If the script exits non-zero with a "pull request moved" message, the PR was force-pushed or pushed to after Step 1. Do not retry with the new SHA and do not strip --expect-head. Re-fetch the diff, re-verify every finding's file and line against it (line numbers shift, and a finding may no longer apply at all), then start the submission flow again wit

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wyattjoh
• Source: wyattjoh/skills
• License: MIT

Install and usage instructions live in the source repository linked above.