Python Code Review

Systematic code review with actionable feedback organized by severity.

Process

1. Gather context

   bashCopy

   git diff --name-only main
   git diff main
   git log main..HEAD --oneline
   

2. Run automated checks

   bashCopy

   ruff check --output-format=json <files>
   vulture --min-confidence=80 <files>
   mypy <files>
   

3. Apply review checklists - see references below

4. Generate report with issues and fix plan

Severity Levels

Review Categories

Apply these checklists to changed files:

1. Architecture - Layer violations, dependency direction, god classes

   • See references/architecture.md

2. Security - Injection, secrets, path traversal, deserialization

   • See references/security.md

3. Quality - Complexity, error handling, performance

   • See references/quality.md

4. Testing - Coverage, assertions, isolation, fixtures

   • See references/testing.md

5. Documentation - Docstrings, README accuracy

   • See references/documentation.md

6. Deployment - Dockerfile, Helm, migrations

   • See references/deployment.md

7. Consistency - Code-docs sync, signature matches

   • See references/consistency.md

Output Format

# Code Review Report

**Status**: PASS | NEEDS_WORK | BLOCKED

## Issues
| Severity | Count |
|----------|-------|
| Critical | N |

### [Category]
- [severity] file:line - description
  - Fix: specific suggestion

## Fix Plan
1. [Issue] - [Action]

Principles

• Be specific: "Add try/except at line 42" not "improve error handling"
• Verify first: Check functions exist before suggesting them
• Focus on changes: Don't refactor untouched code
• Provide working examples