| name | pr-review |
| description | Fetch and review a GitHub pull request with comprehensive analysis — pattern consistency against existing codebase, junior-friendly explanations, documentation links, manual testing steps with edge cases, and Fix Verification Criteria. Requires gh CLI. Usage: /skill:pr-review <PR URL or number> |
PR Review for Junior Engineers
Review a GitHub PR and provide a comprehensive summary with documentation links.
PR URL: $ARGUMENTS
Steps:
-
Parse PR Information
- Extract owner, repo, and PR number from the provided URL
- Format:
https://github.com/{owner}/{repo}/pull/{number}
-
Setup PR for Review
- Save current work:
git stash push -m "PR review backup"
- Note current branch:
git branch --show-current > .pr-review-original-branch
- Checkout PR:
gh pr checkout {number} --repo {owner}/{repo}
- Check for new dependencies:
git diff {original-branch}...HEAD -- package.json requirements.txt Gemfile go.mod
- Only install if dependency files changed
-
Fetch PR Overview
gh pr view {number} --repo {owner}/{repo} --json title,body,state,author,createdAt,files,additions,deletions
gh pr diff {number} --repo {owner}/{repo} - Get the full diff
-
Analyze Changed Files
- Group changes by file type and purpose
- Identify patterns and architectural changes
- Note any new dependencies or libraries added
-
Pattern Consistency Check
-
Create Junior-Friendly Summary
PR Overview
- Purpose: What problem does this PR solve?
- Scope: How many files changed and why?
- Impact: What parts of the system are affected?
Technical Changes Explained
For each significant change:
- What changed: Plain English explanation
- Why it changed: The reasoning behind the change
- How it works: Step-by-step breakdown
Code Patterns Used
- Design patterns implemented
- Best practices followed
- Anti-patterns avoided
-
Documentation Research
-
Learning Points
- Key concepts to understand
- Skills demonstrated in the PR
- Common patterns to remember
-
Testing Strategy
-
Questions to Ask
- Suggest thoughtful questions for code review
- Areas that might need clarification
- Edge cases not covered in tests
Example Output:
# PR Review: Add User Authentication (#123)
## Overview
This PR adds JWT-based authentication to our API. It affects 15 files
and introduces middleware for protecting routes.
## Key Changes Explained
### 1. Authentication Middleware (auth.middleware.ts)
**What**: New file that checks if requests have valid JWT tokens
**Why**: We need to protect sensitive API endpoints
**How**:
- Extracts token from Authorization header
- Verifies token signature
- Attaches user info to request
📚 JWT Documentation: https://jwt.io/introduction
### 2. User Model Updates (user.model.ts)
**What**: Added password hashing methods
**Why**: Never store plain text passwords
**How**: Uses bcrypt to hash passwords before saving
📚 Password Hashing Best Practices: https://auth0.com/blog/hashing-passwords-one-way-road-to-security/
## Pattern Consistency Analysis
### ✅ Follows Existing Patterns:
- **Error Handling**: Uses established `AppError` class from `src/utils/errors.ts`
- **Response Format**: Matches existing API response structure `{ data, status, message }`
- **Middleware Pattern**: Consistent with existing middleware in `src/middleware/`
### ⚠️ Modified Patterns:
- **JWT Storage**: Changed from localStorage to httpOnly cookies (Security improvement)
- Justification: Prevents XSS attacks
### ❌ New Patterns Introduced:
- **Token Refresh**: Added refresh token rotation
- Justification: No existing refresh mechanism found
- Consider: Should align with planned OAuth implementation
## Testing Instructions
### Data Setup
1. Create test database with:
```sql
INSERT INTO users (email, password_hash, role) VALUES
('admin@test.com', '$2b$10$...', 'admin'),
('user@test.com', '$2b$10$...', 'user');
- Set environment variables:
JWT_SECRET=test-secret-key
JWT_EXPIRY=1h
Environment Setup
docker-compose up -d
docker-compose exec app npm install
npm install
npm run db:migrate
Manual Testing Steps
-
Test Login Flow:
- POST /api/auth/login with valid credentials
- Verify JWT token returned
- Check token expiry time
-
Test Protected Routes:
- Access /api/users without token (expect 401)
- Access with valid token (expect 200)
- Access with expired token (expect 401)
Edge Cases to Test
- Login with non-existent user
- Login with wrong password
- Malformed JWT token
- Token with invalid signature
- Concurrent login attempts
Learning Points
- Middleware pattern for cross-cutting concerns
- Importance of password security
- Token-based vs session-based auth
Review Questions
- How are refresh tokens handled?
- What happens when a token expires mid-request?
- Should we add rate limiting to login endpoint?
- Are there tests for all edge cases?
## Cleanup (After Review Complete):
```bash
# When ready to return to original work:
git checkout $(cat .pr-review-original-branch)
# Restore stashed work
git stash pop
# Clean up
rm .pr-review-original-branch
# Optionally delete PR branch locally
git branch -D pr-branch-name
Note: Stay on the PR branch while reviewing and testing. Only run cleanup when completely done.
Notes:
- Requires GitHub CLI (
gh) to be installed and authenticated
- Uses current directory to leverage existing Docker/dependency setup
- Automatically stashes current work and saves original branch
- Works with all project types (Docker, Node, Python, etc.)
- Focuses on education and understanding
- Avoids jargon where possible