Code Review Simplify

Unified code review + simplification. Single-pass, multi-dimensional scoring, adaptive depth. Integrates with evolve-loop auditor and builder phases.

Contents

• Architecture — hybrid pipeline+agentic model
• Single-Pass Flow — read diff once, analyze both dimensions
• Multi-Dimensional Scoring — 4 dimensions with numeric scores
• Adaptive Depth Routing — scale analysis with diff complexity
• Integration Hooks — evolve-loop auditor and builder wiring
• Simplification Catalog — what to simplify and when
• Output Schema — structured review+simplify report

Architecture

Hybrid pipeline+agentic model. Structured passes handle known patterns cheaply; agentic reasoning handles contextual issues that require understanding intent.

Input: git diff (changed files)
         │
         ▼
┌─────────────────────────┐
│  PIPELINE LAYER (fast)  │  Deterministic pattern checks
│  ─────────────────────  │
│  1. Complexity scan     │  Cognitive complexity, nesting depth
│  2. Smell detection     │  22-smell catalog from detect-code-smells
│  3. Security scan       │  OWASP patterns, secrets, injection
│  4. Style check         │  Naming, file size, function length
│  5. Duplication check   │  Near-duplicate code blocks
└─────────┬───────────────┘
          │ Structured findings
          ▼
┌─────────────────────────┐
│  AGENTIC LAYER (deep)   │  LLM-powered contextual analysis
│  ─────────────────────  │
│  6. Logic correctness   │  Edge cases, off-by-one, null handling
│  7. Intent alignment    │  Does change match acceptance criteria?
│  8. Cross-file impact   │  Dependency effects, API contract breaks
│  9. Simplification      │  Extract Method, reduce nesting, dedup
│  10. Compound risk      │  Future maintenance cost assessment
└─────────┬───────────────┘
          │ Contextual findings
          ▼
┌─────────────────────────┐
│  SCORING & REPORT       │  Aggregate into multi-dimensional scores
│  ─────────────────────  │
│  Composite score 0.0-1.0│
│  Per-dimension scores   │
│  Simplification actions │
│  Priority-ranked issues │
└─────────────────────────┘

Why hybrid? Pipeline catches 60-70% of issues at ~5% of the token cost. Agentic layer focuses expensive reasoning on the 30-40% that requires context. Research: Cursor BugBot's biggest quality leap was pipeline→agentic; Anthropic's review dispatches parallel specialist agents.

Token budget: Pipeline layer ~2-5K tokens. Agentic layer ~15-40K tokens (scales with diff). Total: ~20-45K per review pass.

Single-Pass Flow

Read the diff once. Run both review and simplification analysis on the same context. This saves ~40-50% tokens vs. invoking separate review and simplify agents.

Step 1: LOAD (once)

DIFF=$(git diff HEAD~1 --stat)
DIFF_LINES=$(git diff HEAD~1 --numstat | awk '{s+=$1+$2} END {print s}')
CHANGED_FILES=$(git diff HEAD~1 --name-only)

Step 2: PIPELINE (structured checks)

Run deterministic checks on each changed file:

Step 3: AGENTIC (contextual analysis)

LLM analyzes the diff with pipeline findings as context:

Step 4: SCORE & REPORT

Aggregate findings into the multi-dimensional scoring output (see below).

Multi-Dimensional Scoring

Four dimensions, each scored 0.0 to 1.0. Replaces binary PASS/FAIL with actionable numeric scores.

Composite score: composite = 0.35*correctness + 0.25*security + 0.15*performance + 0.25*maintainability

Verdict mapping:

Simplification trigger: If maintainability < 0.7, auto-generate simplification suggestions (see Simplification Catalog).

Confidence: Each dimension includes a confidence (0.0-1.0). If any dimension's confidence < 0.7, escalate to WARN regardless of score.

Adaptive Depth Routing

Scale analysis intensity with diff complexity. Small changes get lightweight review; large changes get full multi-agent analysis.

Security-sensitive detection: Files matching these patterns auto-escalate to full review:

• auth*, *login*, *password*, *token*, *secret*
• *payment*, *billing*, *checkout*
• *eval*, *grader*, *.evolve/evals/*
• Any file in agents/, skills/*/SKILL.md

Risk-based routing: Files with high churn (> 5 commits in last 10 cycles) or high fan-in (imported by > 5 other files) get escalated one tier.

Integration Hooks

Evolve-Loop Auditor Integration

The auditor invokes this skill as an optional enhancement to its review pass:

Auditor Standard Flow:
  1. Read build-report.md
  2. Run code quality checks          ← ENHANCED by pipeline layer
  3. Run security checks               ← ENHANCED by security scan
  4. Run hallucination detection        (unchanged)
  5. Run pipeline integrity checks      (unchanged)
  6. Run eval verification              (unchanged)
  7. Generate verdict                   ← ENHANCED by multi-dimensional scoring

Auditor invocation: When the auditor encounters code changes (not doc-only or config-only), it can invoke this skill's structured checks to supplement its review. The skill's composite score feeds into the auditor's verdict logic.

Configuration in evolve-auditor.md:

### Optional Skill Consultation
- **code-review-simplify**: For code changes, invoke `skills/code-review-simplify/SKILL.md` 
  pipeline layer. Use composite score to supplement verdict. If maintainability < 0.7, 
  append simplification suggestions to audit-report.md.

Evolve-Loop Builder Integration

The builder can invoke this skill post-implementation for self-review:

Builder Self-Review (after implementation, before reporting):
  1. Run eval graders (existing)
  2. Run code-review-simplify lightweight tier
  3. If maintainability < 0.7: apply simplification suggestions before reporting
  4. Include self-review score in build-report.md

Builder invocation: After implementing a task and before writing build-report.md, the builder runs this skill's lightweight tier on its own changes. Simplification suggestions with maintainability < 0.7 are applied inline. This catches issues before the auditor sees them, reducing audit-fix cycles.

Standalone Invocation

The skill can be invoked directly outside the evolve-loop:

# Review + simplify changed files
/code-review-simplify [--tier lightweight|standard|full] [--files <paths>]

Simplification Catalog

When maintainability < 0.7, generate simplification suggestions from this catalog. Prioritize by impact and confidence.

Constraints:

• Only suggest localized refactorings (same file or module). LLMs are weak at cross-module architectural refactoring.
• Max 5 simplification suggestions per review. Focus on highest-impact.
• Each suggestion must include before/after code snippets and estimated complexity reduction.
• Never suggest simplification that changes external behavior (pure refactoring only).

Output Schema

The skill produces a structured report:

# Code Review + Simplify Report

## Summary
- **Tier:** lightweight | standard | full review
- **Changed:** X files, Y lines
- **Composite Score:** 0.XX
- **Verdict:** PASS | WARN | FAIL

## Dimension Scores
| Dimension | Score | Confidence | Key Finding |
|-----------|-------|------------|-------------|
| correctness | 0.X | 0.X | <summary> |
| security | 0.X | 0.X | <summary> |
| performance | 0.X | 0.X | <summary> |
| maintainability | 0.X | 0.X | <summary> |

## Issues (priority-ranked)
| # | Severity | Dimension | File:Line | Description | Suggestion |
|---|----------|-----------|-----------|-------------|-----------|

## Simplification Suggestions
| # | Technique | File:Line | Before (snippet) | After (snippet) | Impact |
|---|----------|-----------|-------------------|-----------------|--------|

## Pipeline Findings
<structured check results>

## Agentic Findings
<contextual analysis results>

JSON variant (for programmatic consumption by auditor/builder):

{
  "tier": "lightweight|standard|full",
  "composite": 0.0,
  "verdict": "PASS|WARN|FAIL",
  "dimensions": {
    "correctness": {"score": 0.0, "confidence": 0.0, "findings": []},
    "security": {"score": 0.0, "confidence": 0.0, "findings": []},
    "performance": {"score": 0.0, "confidence": 0.0, "findings": []},
    "maintainability": {"score": 0.0, "confidence": 0.0, "findings": []}
  },
  "simplifications": [],
  "issueCount": {"critical": 0, "high": 0, "medium": 0, "low": 0}
}