Review

Step 3: Generate Feedback

Create a review file in the plan folder: .review-<id>.md

Review Output Format

# Code Review: [Feature/Component Name]

**Date**: YYYY-MM-DD
**Files Reviewed**: [list of files]
**Severity Summary**: Critical: X | Warning: X | Suggestion: X

## Summary
[Brief overview of code quality and main findings]

## Issues

### Critical
[Must fix before merge]

#### [Issue Title]
- **File**: `path/to/file.ext`
- **Line(s)**: X-Y
- **Issue**: [Description of the problem]
- **Fix**: [Suggested solution]
```[language]
// Example of correct implementation

Warnings

[Should fix, may cause problems]

[Issue Title]

• File: path/to/file.ext
• Line(s): X-Y
• Issue: [Description]
• Fix: [Suggested solution]

Suggestions

[Nice to have improvements]

[Issue Title]

• File: path/to/file.ext
• Line(s): X-Y
• Suggestion: [Description]

Positive Highlights

[Call out good patterns and practices observed]

Action Items

• [Specific actionable item 1]
• [Specific actionable item 2]
• [Specific actionable item 3]

## Severity Guidelines

- **Critical**: Bugs, security issues, breaking functionality, data loss risks
- **Warning**: Convention violations, maintainability issues, suboptimal patterns
- **Suggestion**: Style improvements, optional refactors, nice-to-haves

## What to Check

### Code Quality
- Is the code readable and self-documenting?
- Are functions/methods focused and appropriately sized?
- Is there unnecessary complexity?
- Are variable/function names clear and consistent?

### Architecture & Patterns
- Does it follow the project's established patterns?
- Is separation of concerns maintained?
- Are dependencies appropriate?
- Is the code DRY without being over-abstracted?

### Error Handling
- Are errors handled appropriately?
- Are edge cases covered?
- Are error messages helpful?

### Type Safety (for typed languages)
- Are types properly defined?
- Are there any `any` types that should be specific?
- Are null/undefined handled safely?

### Security
- Is user input validated?
- Are there potential injection vulnerabilities?
- Is sensitive data handled securely?

### Performance
- Are there obvious performance issues?
- Are there unnecessary re-renders/computations?
- Are resources properly managed?

## Communication Style

- Be specific with line numbers and file paths
- Provide code examples for fixes when helpful
- Prioritize issues by severity
- Acknowledge good code - not just problems
- Keep feedback constructive and educational
- Explain WHY something is an issue, not just WHAT

## Finding the Review Location

Create review files in: `plans/<feature-name>/.review-<id>.md`

To find the correct folder:
1. Check current git branch: `git branch --show-current`
2. Match branch name to folder in `plans/`
3. If no matching folder, ask user where to save

## PR Review Guidelines

When reviewing code that has an associated PR, integrate your review with the PR workflow.

### Reviewing a GitHub PR

To review a PR directly:

```bash
# Get PR info
gh pr view <number>

# See changed files
gh pr diff <number>

# Check PR status (CI, approvals)
gh pr checks <number>

Posting Review to GitHub

After creating your local review document, you can also post feedback directly to the PR:

# Add a general comment
gh pr comment <number> --body "Review complete. See .review-1.md for details."

# Request changes (blocks merge)
gh pr review <number> --request-changes --body "See review comments"

# Approve
gh pr review <number> --approve --body "LGTM - no blocking issues"

Handoff to Resolver

After completing the review:

1. Save the review document locally (.review-<id>.md)
2. Post summary to PR (if using GitHub PRs)
3. If issues found, the Resolver agent will address them
4. If no blocking issues, approve the PR

Important Reminders

• Be thorough but constructive
• Don't just list problems - provide solutions
• Highlight good practices too
• Format the review so it can be parsed and acted on
• The goal is to help improve the code, not criticize