Interactive Code Review Skill

Purpose

Provide structured code review workflow after agent implementation iterations. Allows capturing comments with categories and tracking resolution status.

Storage Format

Reviews are stored in .agent/reviews/:

.agent/reviews/
├── YYYY-MM-DD-<short_hash>.md    # Review for specific commit
├── active-review.md               # Currently open review
└── README.md                      # Review folder documentation

Review Document Format

# Code Review: <commit_hash>

**Date**: YYYY-MM-DD HH:MM
**Author**: [user|agent]
**Commit**: <full_hash>
**Branch**: <branch_name>

## Summary

<brief description of changes reviewed>

## Changed Files

| File | Lines Changed | Status |
|------|---------------|--------|
| src/foo.py | +15 -3 | reviewed |
| tests/test_foo.py | +25 | pending |

## Comments

### [CATEGORY] File:Line — Comment Title

**File**: `path/to/file.py`
**Line**: 42-45
**Category**: fix | question | suggestion | concern | praise
**Status**: open | addressed | wont_fix | deferred
**Priority**: critical | high | normal | low

<comment body>

#### Response (if any)

<agent or user response>

---

### [SUGGESTION] src/utils.py:78 — Consider extracting helper

**File**: `src/utils.py`
**Line**: 78
**Category**: suggestion
**Status**: addressed
**Priority**: normal

This block of code appears in multiple places. Consider extracting to a helper function.

#### Response

Extracted to `_format_output()` helper in commit abc123.

---

## Metrics

- Total Comments: X
- Open: X
- Addressed: X
- Won't Fix: X
- Deferred: X

Comment Categories

Category	Icon	Use For
fix	🔧	Required changes, bugs, errors
question	❓	Clarification needed
suggestion	💡	Optional improvements
concern	⚠️	Potential issues, risks
praise	👍	Good patterns, well done

Status Transitions

open → addressed    (when fix is committed)
open → wont_fix     (when decided not to fix with reason)
open → deferred     (when moved to future work)

CLI Integration (Proposed)

# Start review for current changes
aoc review start

# Start review for specific commit
aoc review start <commit>

# View current review
aoc review show

# Add a comment
aoc review comment --file src/foo.py --line 42 --category fix "Fix null check"

# Mark comment as addressed
aoc review resolve <comment_id>

# Mark as won't fix
aoc review wontfix <comment_id> --reason "Out of scope"

# Defer to issue
aoc review defer <comment_id> --issue FEAT-0123

# Complete review
aoc review complete

# Generate summary
aoc review summary

Workflow Integration

After Implementation

User: Review the changes

Agent:
1. Get diff since last commit/baseline
2. Apply agent-ops-critical-review analysis
3. Create review document
4. Present findings organized by category
5. Ask for user feedback

User: [Provides comments]

Agent:
1. Record comments in review document
2. Address fix/question items
3. Commit changes
4. Update comment statuses
5. Present updated review

Integration with Validation

The validation skill can check for unresolved review comments:

## Pre-Commit Checklist

- [ ] All tests pass
- [ ] No lint errors
- [ ] Coverage maintained
- [x] Review comments addressed (3 open → requires resolution)

Review Templates

Quick Review (for small changes)

# Quick Review: <hash>

**Changes**: <summary>

## Comments

- **src/foo.py:23**: [fix] Missing null check
- **src/bar.py:45**: [suggestion] Could simplify with list comprehension

## Status: open/complete

Detailed Review (for PRs/major changes)

Full format as shown above.

Best Practices

1. Review early, review often — Don't let comments accumulate
2. Be specific — Include file paths and line numbers
3. Categorize correctly — Helps prioritize response
4. Track everything — All decisions should be captured
5. Close the loop — Every comment should reach a final status