Manual Review Guide

# Manual Review Guide

**Purpose**: Structured guidance for manual code review integrated with AI review tools.

**Audience**: Developers conducting PR reviews, maintainers configuring review workflows.

---

## Overview

Manual review remains essential even with AI-powered tools like Greptile and CodeRabbit. This guide provides a systematic approach to combine human judgment with AI insights for comprehensive code quality.

**Review Philosophy**:
- **AI First, Human Final**: Use AI tools for breadth, manual review for depth
- **Structured Process**: Follow systematic checklist to avoid missing critical issues
- **Context Matters**: Apply judgment based on project stage, risk, and complexity
- **Documentation Required**: Every PR needs clear explanation of changes and reasoning

---

## Review Workflow Integration

This guide integrates with the Forge 9-Stage TDD Workflow:

```
/status → /research → /plan → /dev → /validate → /ship → /review → /premerge → /verify
                                                           ↑
                                                  You are here
```

### When to Use This Guide

- **Stage 7 (/review)**: Address ALL PR feedback from GitHub Actions, Greptile, SonarCloud, and manual reviewers
- **After AI Review**: When Greptile or CodeRabbit has completed initial analysis
- **Before Merge**: Final verification before approving PR
- **Post-Merge**: Documentation verification in /verify stage



## Part 1: AI Review Tools Best Practices

### Greptile - Semantic Understanding
- Use .claude/scripts/greptile-resolve.sh for systematic thread handling
- Always reply and resolve threads after fixes
- See .claude/rules/greptile-review-process.md for detailed workflow

### CodeRabbit - Multi-Model Review
- Address security issues immediately
- Consider performance suggestions with benchmarks
- Apply style suggestions for consistency

### SonarCloud - Static Analysis
- Coverage ≥80% on new code
- 0 security hotspots unreviewed
- Use /sonarcloud skill for PR-specific issues

---

## Part 2: Manual Review Checklist

### 1. Functional Correctness
- ☐ Code matches PR description
- ☐ Edge cases handled
- ☐ Error messages clear
- ☐ Invalid input handled gracefully

### 2. Security (OWASP Top 10)
- ☐ Authorization before sensitive ops
- ☐ Data encrypted at rest/transit
- ☐ SQL queries parameterized
- ☐ No code injection risks

### 3. Testing Quality
- ☐ Tests for new code
- ☐ Edge cases covered
- ☐ TDD compliance (test commits before feat commits)

### 4. Code Quality
- ☐ Self-documenting code
- ☐ Single responsibility functions
- ☐ No duplication (DRY)
- ☐ Clear organization

### 5. Performance
- ☐ Efficient algorithms
- ☐ Optimized queries
- ☐ No memory leaks

### 6. Documentation
- ☐ Public APIs documented
- ☐ PR explains why, not just what
- ☐ README updated if needed

---

## Summary

**Manual Review Essentials**:
- Use AI tools for pattern detection
- Apply human judgment for context
- Follow systematic checklist
- Verify security, testing, documentation

**Integration**: Stage 7 (/review) → Address ALL feedback systematically

**Key**: Trust AI for breadth, humans for depth. Best results combine both.