aaron-pr-review - SKILL.md Agent Skill

name: aaron-pr-review description: | Review GitHub pull requests with Aaron's specific workflow and feedback format. Use when:

User says "/aaron-pr-review" followed by a PR URL, or "review this PR"
User provides a GitHub PR URL and wants a code review
User asks for PR feedback in Aaron's style

This skill produces markdown review documents written from aaronbrethorst's perspective with prioritized feedback (critical, important, fit-and-finish) and a kind but firm tone.

Includes specialized review agents for deep analysis: - code-reviewer: General code quality and CLAUDE.md compliance - code-simplifier: Code clarity and maintainability - comment-analyzer: Comment accuracy and documentation quality - pr-test-analyzer: Test coverage quality and completeness - silent-failure-hunter: Error handling and silent failures - type-design-analyzer: Type design and invariants allowed-tools: ["Bash", "Glob", "Grep", "Read", "Task", "cat:*", "pbcopy"] argument-hint: "[PR URL or number]"

Aaron's PR Review Workflow

Setup

Before starting the review, perform these setup steps:

Clean up previous reviews: Delete any existing pr-*.md files in the current directory:
```
rm -f pr-*.md
```

Ensure latest commits: To guarantee you're reviewing the latest code, use gh pr checkout which correctly handles fork remotes (unlike git fetch origin which only fetches from the upstream repo):

# Stash any uncommitted changes
git stash push -m "aaron-pr-review: auto-stash before branch refresh"

# Delete any stale local branch, then checkout fresh from GitHub
PR_BRANCH=$(gh pr view <number> --json headRefName -q .headRefName)
git checkout main
git branch -D "$PR_BRANCH" 2>/dev/null || true
gh pr checkout <number> --force

# Restore stashed changes
git stash pop 2>/dev/null || true

Verify you have the latest commit: Compare your local HEAD against what GitHub reports. If these don't match, stop and investigate before reviewing.

LOCAL_SHA=$(git rev-parse HEAD)
REMOTE_SHA=$(gh pr view <number> --json headRefOid -q .headRefOid)
if [ "$LOCAL_SHA" != "$REMOTE_SHA" ]; then
  echo "ERROR: Local HEAD ($LOCAL_SHA) does not match PR head ($REMOTE_SHA)"
  echo "Do NOT proceed with the review until this is resolved."
else
  echo "OK: Reviewing commit $LOCAL_SHA"
fi

Pre-Review Analysis

Before reviewing code changes, always check existing PR comments first:

Use gh pr view <number> --comments to scan for prior feedback from aaronbrethorst
If prior feedback exists:
- Identify which items the author has addressed
- Check if author provided clarifications for items they chose not to address
- Focus your review on new/unaddressed changes
- Treat author explanations with courtesy—they likely have good reasons

Code Review Process

Fetch PR details: gh pr view <number> --json title,body,author,files,additions,deletions
Get the diff: gh pr diff <number>
Read changed files to understand context
Run tests if applicable: make test or equivalent
Check lint/format: make lint or equivalent
Identify file types to determine which agents apply

Agent Applicability Assessment

MANDATORY: Before launching agents, assess each one's applicability to this PR. Assign confidence scores (0-100) and use agents scoring ≥ 80.

Output format:

## Agent Applicability Assessment

| Agent | Confidence | Rationale | Use? |
|-------|------------|-----------|------|
| code-reviewer | [0-100] | [Brief reason] | [Yes/No] |
| silent-failure-hunter | [0-100] | [Brief reason] | [Yes/No] |
| pr-test-analyzer | [0-100] | [Brief reason] | [Yes/No] |
| comment-analyzer | [0-100] | [Brief reason] | [Yes/No] |
| type-design-analyzer | [0-100] | [Brief reason] | [Yes/No] |
| code-simplifier | [0-100] | [Brief reason] | [Yes/No] |

For detailed scoring guidelines and examples, see applicability.md.

Launch Review Agents

After assessment, launch all agents marked "Yes" via the Task tool.

Sequential: One agent at a time—easier to understand, good for interactive review.

Parallel: Launch all simultaneously—faster for comprehensive review (user can request with parallel).

For agent descriptions and invocation details, see agents.md.

Aggregate Results

After agents complete, summarize findings as a Markdown file with the following elements

IMPORTANT: Never include agent names (e.g., [code-reviewer], [silent-failure-hunter]) in the review output. The review must read as if written entirely by aaronbrethorst—agent names are internal implementation details.

## Critical Issues (X found)
- Issue description [file:line]

## Important Issues (X found)
- Issue description [file:line]

## Suggestions (X found)
- Suggestion [file:line]

## Strengths
- What's well-done in this PR

## Recommended Action
1. Fix critical issues first
2. Address important issues
3. Consider suggestions
4. Re-run review after fixes

Review Output

When finished, provide:

Verbal verdict: Tell the user "merge" or "request changes"—there is NO middle ground like "merge after this change"
Written review: Create pr-{id}.md in the current directory

Verdict rules:

Merge: The PR is ready to merge as-is. If there are minor issues that don't need to be resolved in the scope of this PR, you MUST create a GitHub issue (via gh issue create) tracking the remaining fixes before giving a Merge verdict. Reference the new issue in the review document.
Request Changes: The PR has issues that must be resolved before merging.

For review document templates (first-time, subsequent, ready-to-merge), see templates.md.

Post-Review

After writing the review document, ask: "Would you like me to copy the markdown to your clipboard?"

When user confirms, run:

cat pr-{id}.md | pbcopy

Style Guidelines

Tone: Kind but firm. Be encouraging while being clear about requirements.
Uniqueness: Put a unique spin on the greeting/compliment for each PR—avoid robotic repetition.
Specificity: Reference actual code, file names, and line numbers where relevant.
Author's name: Use their first name from the PR author info.
Never mention PR count: Do not reference how many PRs the author has made. Never say "first PR", "welcome as a new contributor", "your Nth contribution", or anything similar. Focus on the code, not the author's contribution history.

Additional Resources

For review templates, see templates.md
For agent descriptions, see agents.md
For applicability guidelines, see applicability.md
For usage examples, see examples.md
For iOS code reviews, use the sosumi MCP server to fetch official Apple documentation as needed.