# Code Review Agent Skill

AI-powered code review that catches real issues, not just style nits. Inspired by Stripe's 1K+ agent PR/week workflow.

## When to Use
- User asks to review code, a PR, or a diff
- User pastes code and wants feedback
- Automated review as part of a CI/CD-like workflow

## How It Works

### Input
- Code diff, file contents, or PR description
- Optional: repo context, coding standards, language

### Review Process

1. **Understand Intent**: What is this code trying to do? Read any PR description or commit message first.

2. **Categorize Findings** (in order of severity):
   - 🔴 **Bugs**: Logic errors, null refs, race conditions, security holes
   - 🟡 **Design Issues**: Poor abstractions, tight coupling, missing error handling, scalability concerns
   - 🟢 **Improvements**: Better patterns, performance wins, readability
   - ⚪ **Nits**: Style, naming, formatting (mention sparingly)

3. **For Each Finding**:
   - Cite the exact line/section
   - Explain WHY it's a problem (not just what)
   - Suggest a concrete fix with code
   - Rate confidence: high/medium/low

4. **Summary**: 
   - Overall assessment (approve / request changes / needs discussion)
   - Top 3 most important items
   - What the code does well (genuine praise, not filler)

### Quality Rules
- **No sycophancy**: Don't say "great code!" then list 15 issues
- **Prioritize**: Better to deeply explain 3 real issues than shallow-flag 20
- **Be specific**: "This could fail when X" beats "error handling could be improved"
- **Suggest, don't lecture**: Show the fix, skip the CS101 explanation
- **Acknowledge trade-offs**: If something looks wrong but might be intentional, ask rather than flag

### Output Format

```markdown
## Code Review

**Overall**: [Approve ✅ | Changes Requested 🔄 | Needs Discussion 💬]

### Findings

#### 🔴 [Bug Title] (Line X)
[Explanation + fix]

#### 🟡 [Design Issue] (Line Y-Z) 
[Explanation + suggestion]

### What's Good
- [Genuine positive observations]

### Summary
[2-3 sentence wrap-up with top priorities]
```

## Anti-Patterns to Avoid
- Reviewing style when there are bugs (fix the fire, not the wallpaper)
- Flagging things the linter should catch
- Suggesting rewrites when the code works and is readable
- Being vague: "consider error handling" (WHERE? HOW?)