PaperclipOrg
Claude Agent Skill · by Wshobson

Code Review Excellence

Code Review Excellence guides developers and team leads through conducting effective code reviews that balance quality assurance with constructive collaboration

Install
Terminal · npx
$npx skills add https://github.com/wshobson/agents --skill code-review-excellence
Works with Paperclip

How Code Review Excellence fits into a Paperclip company.

Code Review Excellence drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.

S
SaaS FactoryPaired

Pre-configured AI company — 18 agents, 18 skills, one-time purchase.

$27$59
Explore pack
Source file
SKILL.md529 lines
Expand
---name: code-review-excellencedescription: Master effective code review practices to provide constructive feedback, catch bugs early, and foster knowledge sharing while maintaining team morale. Use when reviewing pull requests, establishing review standards, or mentoring developers.--- # Code Review Excellence Transform code reviews from gatekeeping to knowledge sharing through constructive feedback, systematic analysis, and collaborative improvement. ## When to Use This Skill - Reviewing pull requests and code changes- Establishing code review standards for teams- Mentoring junior developers through reviews- Conducting architecture reviews- Creating review checklists and guidelines- Improving team collaboration- Reducing code review cycle time- Maintaining code quality standards ## Core Principles ### 1. The Review Mindset **Goals of Code Review:** - Catch bugs and edge cases- Ensure code maintainability- Share knowledge across team- Enforce coding standards- Improve design and architecture- Build team culture **Not the Goals:** - Show off knowledge- Nitpick formatting (use linters)- Block progress unnecessarily- Rewrite to your preference ### 2. Effective Feedback **Good Feedback is:** - Specific and actionable- Educational, not judgmental- Focused on the code, not the person- Balanced (praise good work too)- Prioritized (critical vs nice-to-have) ```markdown❌ Bad: "This is wrong."✅ Good: "This could cause a race condition when multiple usersaccess simultaneously. Consider using a mutex here." ❌ Bad: "Why didn't you use X pattern?"✅ Good: "Have you considered the Repository pattern? It wouldmake this easier to test. Here's an example: [link]" ❌ Bad: "Rename this variable."✅ Good: "[nit] Consider `userCount` instead of `uc` forclarity. Not blocking if you prefer to keep it."``` ### 3. Review Scope **What to Review:** - Logic correctness and edge cases- Security vulnerabilities- Performance implications- Test coverage and quality- Error handling- Documentation and comments- API design and naming- Architectural fit **What Not to Review Manually:** - Code formatting (use Prettier, Black, etc.)- Import organization- Linting violations- Simple typos ## Review Process ### Phase 1: Context Gathering (2-3 minutes) ```markdownBefore diving into code, understand: 1. Read PR description and linked issue2. Check PR size (>400 lines? Ask to split)3. Review CI/CD status (tests passing?)4. Understand the business requirement5. Note any relevant architectural decisions``` ### Phase 2: High-Level Review (5-10 minutes) ```markdown1. **Architecture & Design**   - Does the solution fit the problem?   - Are there simpler approaches?   - Is it consistent with existing patterns?   - Will it scale? 2. **File Organization**   - Are new files in the right places?   - Is code grouped logically?   - Are there duplicate files? 3. **Testing Strategy**   - Are there tests?   - Do tests cover edge cases?   - Are tests readable?``` ### Phase 3: Line-by-Line Review (10-20 minutes) ```markdownFor each file: 1. **Logic & Correctness**   - Edge cases handled?   - Off-by-one errors?   - Null/undefined checks?   - Race conditions? 2. **Security**   - Input validation?   - SQL injection risks?   - XSS vulnerabilities?   - Sensitive data exposure? 3. **Performance**   - N+1 queries?   - Unnecessary loops?   - Memory leaks?   - Blocking operations? 4. **Maintainability**   - Clear variable names?   - Functions doing one thing?   - Complex code commented?   - Magic numbers extracted?``` ### Phase 4: Summary & Decision (2-3 minutes) ```markdown1. Summarize key concerns2. Highlight what you liked3. Make clear decision:   - ✅ Approve   - 💬 Comment (minor suggestions)   - 🔄 Request Changes (must address)4. Offer to pair if complex``` ## Review Techniques ### Technique 1: The Checklist Method ```markdown## Security Checklist - [ ] User input validated and sanitized- [ ] SQL queries use parameterization- [ ] Authentication/authorization checked- [ ] Secrets not hardcoded- [ ] Error messages don't leak info ## Performance Checklist - [ ] No N+1 queries- [ ] Database queries indexed- [ ] Large lists paginated- [ ] Expensive operations cached- [ ] No blocking I/O in hot paths ## Testing Checklist - [ ] Happy path tested- [ ] Edge cases covered- [ ] Error cases tested- [ ] Test names are descriptive- [ ] Tests are deterministic``` ### Technique 2: The Question Approach Instead of stating problems, ask questions to encourage thinking: ```markdown❌ "This will fail if the list is empty."✅ "What happens if `items` is an empty array?" ❌ "You need error handling here."✅ "How should this behave if the API call fails?" ❌ "This is inefficient."✅ "I see this loops through all users. Have we consideredthe performance impact with 100k users?"``` ### Technique 3: Suggest, Don't Command ````markdown## Use Collaborative Language ❌ "You must change this to use async/await"✅ "Suggestion: async/await might make this more readable:`typescript    async function fetchUser(id: string) {        const user = await db.query('SELECT * FROM users WHERE id = ?', id);        return user;    }    `What do you think?" ❌ "Extract this into a function"✅ "This logic appears in 3 places. Would it make sense toextract it into a shared utility function?"```` ### Technique 4: Differentiate Severity ```markdownUse labels to indicate priority: 🔴 [blocking] - Must fix before merge🟡 [important] - Should fix, discuss if disagree🟢 [nit] - Nice to have, not blocking💡 [suggestion] - Alternative approach to consider📚 [learning] - Educational comment, no action needed🎉 [praise] - Good work, keep it up! Example:"🔴 [blocking] This SQL query is vulnerable to injection.Please use parameterized queries." "🟢 [nit] Consider renaming `data` to `userData` for clarity." "🎉 [praise] Excellent test coverage! This will catch edge cases."``` ## Language-Specific Patterns ### Python Code Review ```python# Check for Python-specific issues # ❌ Mutable default argumentsdef add_item(item, items=[]):  # Bug! Shared across calls    items.append(item)    return items # ✅ Use None as defaultdef add_item(item, items=None):    if items is None:        items = []    items.append(item)    return items # ❌ Catching too broadtry:    result = risky_operation()except:  # Catches everything, even KeyboardInterrupt!    pass # ✅ Catch specific exceptionstry:    result = risky_operation()except ValueError as e:    logger.error(f"Invalid value: {e}")    raise # ❌ Using mutable class attributesclass User:    permissions = []  # Shared across all instances! # ✅ Initialize in __init__class User:    def __init__(self):        self.permissions = []``` ### TypeScript/JavaScript Code Review ```typescript// Check for TypeScript-specific issues // ❌ Using any defeats type safetyfunction processData(data: any) {  // Avoid any    return data.value;} // ✅ Use proper typesinterface DataPayload {    value: string;}function processData(data: DataPayload) {    return data.value;} // ❌ Not handling async errorsasync function fetchUser(id: string) {    const response = await fetch(`/api/users/${id}`);    return response.json();  // What if network fails?} // ✅ Handle errors properlyasync function fetchUser(id: string): Promise<User> {    try {        const response = await fetch(`/api/users/${id}`);        if (!response.ok) {            throw new Error(`HTTP ${response.status}`);        }        return await response.json();    } catch (error) {        console.error('Failed to fetch user:', error);        throw error;    }} // ❌ Mutation of propsfunction UserProfile({ user }: Props) {    user.lastViewed = new Date();  // Mutating prop!    return <div>{user.name}</div>;} // ✅ Don't mutate propsfunction UserProfile({ user, onView }: Props) {    useEffect(() => {        onView(user.id);  // Notify parent to update    }, [user.id]);    return <div>{user.name}</div>;}``` ## Advanced Review Patterns ### Pattern 1: Architectural Review ```markdownWhen reviewing significant changes: 1. **Design Document First**   - For large features, request design doc before code   - Review design with team before implementation   - Agree on approach to avoid rework 2. **Review in Stages**   - First PR: Core abstractions and interfaces   - Second PR: Implementation   - Third PR: Integration and tests   - Easier to review, faster to iterate 3. **Consider Alternatives**   - "Have we considered using [pattern/library]?"   - "What's the tradeoff vs. the simpler approach?"   - "How will this evolve as requirements change?"``` ### Pattern 2: Test Quality Review ```typescript// ❌ Poor test: Implementation detail testingtest('increments counter variable', () => {    const component = render(<Counter />);    const button = component.getByRole('button');    fireEvent.click(button);    expect(component.state.counter).toBe(1);  // Testing internal state}); // ✅ Good test: Behavior testingtest('displays incremented count when clicked', () => {    render(<Counter />);    const button = screen.getByRole('button', { name: /increment/i });    fireEvent.click(button);    expect(screen.getByText('Count: 1')).toBeInTheDocument();}); // Review questions for tests:// - Do tests describe behavior, not implementation?// - Are test names clear and descriptive?// - Do tests cover edge cases?// - Are tests independent (no shared state)?// - Can tests run in any order?``` ### Pattern 3: Security Review ```markdown## Security Review Checklist ### Authentication & Authorization - [ ] Is authentication required where needed?- [ ] Are authorization checks before every action?- [ ] Is JWT validation proper (signature, expiry)?- [ ] Are API keys/secrets properly secured? ### Input Validation - [ ] All user inputs validated?- [ ] File uploads restricted (size, type)?- [ ] SQL queries parameterized?- [ ] XSS protection (escape output)? ### Data Protection - [ ] Passwords hashed (bcrypt/argon2)?- [ ] Sensitive data encrypted at rest?- [ ] HTTPS enforced for sensitive data?- [ ] PII handled according to regulations? ### Common Vulnerabilities - [ ] No eval() or similar dynamic execution?- [ ] No hardcoded secrets?- [ ] CSRF protection for state-changing operations?- [ ] Rate limiting on public endpoints?``` ## Giving Difficult Feedback ### Pattern: The Sandwich Method (Modified) ```markdownTraditional: Praise + Criticism + Praise (feels fake) Better: Context + Specific Issue + Helpful Solution Example:"I noticed the payment processing logic is inline in thecontroller. This makes it harder to test and reuse. [Specific Issue]The calculateTotal() function mixes tax calculation,discount logic, and database queries, making it difficultto unit test and reason about. [Helpful Solution]Could we extract this into a PaymentService class? Thatwould make it testable and reusable. I can pair with youon this if helpful."``` ### Handling Disagreements ```markdownWhen author disagrees with your feedback: 1. **Seek to Understand**   "Help me understand your approach. What led you to   choose this pattern?" 2. **Acknowledge Valid Points**   "That's a good point about X. I hadn't considered that." 3. **Provide Data**   "I'm concerned about performance. Can we add a benchmark   to validate the approach?" 4. **Escalate if Needed**   "Let's get [architect/senior dev] to weigh in on this." 5. **Know When to Let Go**   If it's working and not a critical issue, approve it.   Perfection is the enemy of progress.``` ## Best Practices 1. **Review Promptly**: Within 24 hours, ideally same day2. **Limit PR Size**: 200-400 lines max for effective review3. **Review in Time Blocks**: 60 minutes max, take breaks4. **Use Review Tools**: GitHub, GitLab, or dedicated tools5. **Automate What You Can**: Linters, formatters, security scans6. **Build Rapport**: Emoji, praise, and empathy matter7. **Be Available**: Offer to pair on complex issues8. **Learn from Others**: Review others' review comments ## Common Pitfalls - **Perfectionism**: Blocking PRs for minor style preferences- **Scope Creep**: "While you're at it, can you also..."- **Inconsistency**: Different standards for different people- **Delayed Reviews**: Letting PRs sit for days- **Ghosting**: Requesting changes then disappearing- **Rubber Stamping**: Approving without actually reviewing- **Bike Shedding**: Debating trivial details extensively ## Templates ### PR Review Comment Template ```markdown## Summary [Brief overview of what was reviewed] ## Strengths - [What was done well]- [Good patterns or approaches] ## Required Changes 🔴 [Blocking issue 1]🔴 [Blocking issue 2] ## Suggestions 💡 [Improvement 1]💡 [Improvement 2] ## Questions ❓ [Clarification needed on X]❓ [Alternative approach consideration] ## Verdict ✅ Approve after addressing required changes```