Code Review

Code Review Workflow

Use this workflow to review git changes with evidence-backed findings and risk-aware verdicts.

Step 1: Determine Review Target

Identify what to review from the user's request.

Always confirm the target before proceeding:

git --no-pager show --stat <commit_hash>
# or for staged changes:
git --no-pager diff --cached --stat

Step 2: Retrieve the Diff

Get the full diff for the review target. Refer to git_operations.md for detailed commands and fallback handling (root commits, merge commits, range stabilization).

# Single commit
git --no-pager show <commit_hash>

# Staged changes
git --no-pager diff --cached

# Commit range
git --no-pager diff <start_hash>^..<end_hash>

# File-scoped
git --no-pager show <commit_hash> -- <file_path>

Step 3: Classify Changes and Filter Noise

Categorize each changed file and filter out noise before deep review. This prevents wasting review effort on non-reviewable content.

File Categories

Noise Filtering

Skip line-by-line review for these — check consistency/integrity only:

Review Depth by Scale

Always Full-Review (Regardless of Scale)

• Security/auth/authorization files
• Data schema, migration, persistence contracts
• Runtime entrypoints and routing bindings
• Critical production config files

Step 4: Analyze Reviewable Files

Read the full context of each reviewable file to understand the change, not just the diff. Focus on:

• What behavior changed and why
• Whether the change is correct and complete
• Edge cases, error handling, boundary conditions
• Consistency with surrounding code patterns

Step 5: Trace Impact

Identify who/what is affected by the changes. Refer to impact_detection.md for detailed techniques.

Key actions:

1. Find consumers — search for references to changed symbols, APIs, contracts
2. Check exposure — is the changed entity publicly consumed or internal-only?
3. Detect breaking changes — required inputs increased? Output contract changed? Symbols removed/renamed?
4. Check test coverage — do tests cover the changed behavior paths?

# Find direct callers
rg -F "symbolName(" .
# Find broader references
rg "symbolName" .

Breaking Change Signals

If a breaking change has normalized consumers > 0, classify at least as Critical candidate.

Step 6: Classify Findings

Assign each finding a severity and confidence level.

Severity Levels

Critical

Immediate high risk to security, data integrity, availability, or external contracts.

• Security exposure: injection, credential leakage, auth bypass
• Data integrity: corruption, irreversible mutation, destructive migration without rollback
• Availability: crash loops, deadlock, unbounded resource exhaustion
• Breaking contract: incompatible changes on consumed public interfaces
• Rollback gap: no rollback path for high-impact operational changes

Major

Incorrect behavior, reliability degradation, or high operational cost.

• Behavioral defects: wrong branch logic, boundary errors, invalid fallbacks
• Performance: unbounded processing, repeated expensive ops
• Error handling gaps: swallowed failures, incorrect retries
• Concurrency/race conditions
• Observability regression: lost diagnostic context
• Config semantics drift without compatibility handling

Minor

Maintainability, readability, or medium-term quality concerns.

• Excessive complexity, duplicated logic
• Ambiguous naming, unclear control flow
• Tight coupling, low cohesion

Nit

Low-impact polish and consistency.

• Style/formatting drift
• Naming clarity improvements
• Outdated comments

Critical vs Major Boundary

Confidence Tiers

Escalation Rule

A Major finding becomes a REQUEST_CHANGES candidate when ALL of:

• Impacts a critical domain (auth, payment, data integrity, availability)
• High user/service/data impact
• Confidence is Medium or High

Step 7: Determine Verdict

Combine findings into a final verdict.

Baseline Rules

Risk-Weighted Adjustment (Internal Logic)

Use internally to validate the baseline verdict — do NOT output the score:

• Severity weights: Critical=10, Major=5, Minor=2, Nit=1
• Confidence factor: High=1.0, Medium=0.7, Low=0.4
• Critical domain bonus: +4 per finding in auth/payment/data integrity/availability

Confidence-Aware Handling

Step 8: Generate Report

Output the review using the format in output_format.md.

Key requirements:

• Group findings by severity (default) or by file if requested
• Each finding must include: file location, issue, evidence, impact, confidence tier, and suggestion
• State analysis limitations honestly (unverifiable areas, sampling scope)
• Include a Highlights section when patch quality deserves recognition
• End with a clear verdict and decision rationale

Tools

• Git CLI: Commit metadata, diffs, history, range context
• Search tools (rg): Consumer tracing, reference lookup, test coverage checks

Reference Files

Converted and distributed by TomeVault — claim your Tome and manage your conversions.