claw-code/.guardrails/docs/workflows/CODE_REVIEW.md

# Code Review Process

> Agent self-review and human review escalation.

**Related:** [TESTING_VALIDATION.md](./TESTING_VALIDATION.md) | [AGENT_GUARDRAILS.md](../AGENT_GUARDRAILS.md)

---

## Overview

This document defines the code review process for AI agents, including self-review checklists, when to escalate to human reviewers, and review standards.

---

## Agent Self-Review Checklist

**Before committing ANY code change, complete this self-review:**

### Code Quality

```
[ ] Code is syntactically correct (syntax check passes)
[ ] Code follows existing style/patterns in the file
[ ] No unnecessary complexity added
[ ] No code duplication introduced
[ ] Variable/function names are clear and descriptive
[ ] No hardcoded values that should be configurable
```

### Security

```
[ ] No secrets, credentials, or API keys in code
[ ] No SQL injection vulnerabilities
[ ] No XSS vulnerabilities (if web code)
[ ] No command injection vulnerabilities
[ ] Input validation present where needed
[ ] No sensitive data logged or exposed
[ ] Test code does not access production database
[ ] Production code does not access test database
[ ] Test users not present in production code
[ ] Production credentials not in test files
[ ] Separate test/production environments verified
```

### Functionality

```
[ ] Change accomplishes the stated goal
[ ] Edge cases considered and handled
[ ] Error handling is appropriate
[ ] No unintended side effects
[ ] Backwards compatibility maintained (if applicable)
```

### Scope

```
[ ] Only files in scope were modified
[ ] No "improvements" to unrelated code
[ ] No feature creep
[ ] No unnecessary refactoring
```

### Testing

```
[ ] Related tests pass
[ ] New tests added if needed
[ ] Test coverage maintained or improved
[ ] Manual verification confirms behavior
```

---

## When to Request Human Review

### Always Request Human Review For:

```
MANDATORY HUMAN REVIEW:

[ ] Security-related changes (auth, encryption, permissions)
[ ] Database schema changes
[ ] API contract changes
[ ] Payment/financial code
[ ] User data handling changes
[ ] Infrastructure/deployment changes
[ ] Changes to security configurations
[ ] Code affecting compliance (GDPR, HIPAA, etc.)
[ ] Test/production separation unclear
[ ] Database connection strings not environment-specific
[ ] Mixed test/production code
[ ] Any change you're uncertain about
```

### Consider Human Review For:

```
RECOMMENDED HUMAN REVIEW:

[ ] Complex algorithms or logic
[ ] Performance-critical code
[ ] Large refactoring efforts
[ ] Changes touching multiple systems
[ ] Code in unfamiliar areas
[ ] First contribution to a codebase
```

### Human Review Not Required For:

```
SKIP HUMAN REVIEW (unless policy requires):

[ ] Simple typo fixes
[ ] Comment/documentation updates
[ ] Formatting changes
[ ] Adding tests for existing code
[ ] Minor bug fixes with clear scope
```

---

## Review Focus Areas

### Security Review Focus

```
LOOK FOR:
- Authentication/authorization bypasses
- Injection vulnerabilities (SQL, command, XSS)
- Sensitive data exposure
- Insecure cryptography
- Missing input validation
- Hardcoded secrets
- Insecure defaults
```

### Performance Review Focus

```
LOOK FOR:
- N+1 query problems
- Missing indexes on queried fields
- Unnecessary loops or iterations
- Memory leaks
- Blocking operations in async code
- Missing caching opportunities
- Large payload sizes
```

### Logic Review Focus

```
LOOK FOR:
- Off-by-one errors
- Null/undefined handling
- Race conditions
- Incorrect comparisons
- Missing edge cases
- Incorrect error handling
- State management issues
```

---

## Review Comment Standards

### Writing Review Comments

```
GOOD COMMENT STRUCTURE:

[SEVERITY] [AREA]: Description

What: Explain the issue
Why: Explain why it's a problem
Suggestion: Provide fix if possible

SEVERITY LEVELS:
- BLOCKER: Must fix before merge
- MAJOR: Should fix, but can discuss
- MINOR: Nice to have, optional
- NIT: Style/preference, definitely optional
```

### Example Comments

```
BLOCKER [Security]: SQL injection vulnerability

What: User input is concatenated directly into SQL query
Why: Allows attackers to execute arbitrary SQL
Suggestion: Use parameterized query instead

---

MAJOR [Performance]: N+1 query in loop

What: Each iteration makes a database call
Why: Will be slow with large datasets
Suggestion: Batch fetch before loop

---

NIT [Style]: Inconsistent naming

What: Using camelCase here but snake_case elsewhere
Why: Consistency improves readability
Suggestion: Use snake_case to match file convention
```

---

## Approval Requirements

### Standard Changes

```
APPROVAL REQUIREMENTS:

- 1 approval from code owner OR
- 1 approval from team member

PLUS:
- All CI checks pass
- No unresolved blocking comments
```

### Sensitive Changes

```
ELEVATED APPROVAL REQUIREMENTS:

- Security changes: Security team approval
- Database changes: DBA approval
- API changes: API owner approval
- Deployment changes: DevOps approval
```

---

## Escalation Procedures

### When Agent Should Escalate

```
ESCALATE TO HUMAN WHEN:

1. Change touches security-sensitive code
   → Request security review

2. Uncertain about correctness
   → Ask for verification

3. Multiple valid approaches exist
   → Ask for guidance

4. Change has broad impact
   → Request architecture review

5. Tests are flaky or unclear
   → Request testing guidance

6. Performance implications unclear
   → Request performance review
```

### How to Escalate

```
ESCALATION FORMAT:

"I've completed [task] but recommend human review before merging.

REASON: [Why escalation is needed]

SPECIFIC CONCERNS:
- [Concern 1]
- [Concern 2]

CHANGES MADE:
- [Change 1]
- [Change 2]

REQUEST: Please review [specific areas]"
```

---

## Review Workflow

### Agent Self-Review Flow

```
COMPLETE CHANGE
    ↓
RUN SELF-REVIEW CHECKLIST
    ↓
ALL CHECKS PASS? ──NO──→ FIX ISSUES → RETRY
    ↓ YES
NEEDS HUMAN REVIEW? ──YES──→ REQUEST REVIEW → WAIT
    ↓ NO
COMMIT AND PROCEED
```

### Human Review Flow

```
REVIEW REQUESTED
    ↓
HUMAN REVIEWS CODE
    ↓
COMMENTS/APPROVES
    ↓
AGENT ADDRESSES COMMENTS
    ↓
RE-REVIEW IF NEEDED
    ↓
APPROVED → MERGE
```

---

## Quick Reference

```
+------------------------------------------------------------------+
|              CODE REVIEW QUICK REFERENCE                          |
+------------------------------------------------------------------+
| SELF-REVIEW BEFORE COMMIT:                                        |
|   [ ] Syntax correct                                              |
|   [ ] Tests pass                                                  |
|   [ ] No secrets in code                                          |
|   [ ] Only expected files changed                                 |
|   [ ] Style matches existing code                                 |
|   [ ] Test/production separation verified                         |
+------------------------------------------------------------------+
| REQUEST HUMAN REVIEW FOR:                                         |
|   • Security changes                                              |
|   • Database changes                                              |
|   • Payment code                                                  |
|   • Test/production separation unclear                            |
|   • Any uncertainty                                               |
+------------------------------------------------------------------+
| ESCALATION:                                                       |
|   1. Complete self-review                                         |
|   2. Identify specific concerns                                   |
|   3. Request review with clear description                        |
|   4. Wait for approval before merge                               |
+------------------------------------------------------------------+
```

---

**Last Updated:** 2026-01-14
**Authored by:** TheArchitectit
**Document Owner:** Project Maintainers
**Line Count:** ~280