Simplify

Overview

When to Use

• The user wants a

  /simplify

  -style cleanup pass before

  reviewer

  or

  code-reviewer

• A feature is complete and the diff likely contains duplication, rough edges, or avoidable inefficiency
• You want to reduce avoidable reviewer comments before formal review
• The change spans enough files or logic that one simplification pass is not enough

• Tiny diffs where a single local cleanup is enough
• Behavior changes, feature work, or bug fixes that alter requirements
• Large architectural redesigns across untouched modules
• Formal spec validation or security review

Place in Review Flow

implement -> simplify -> code-reviewer and/or reviewer -> receiving-code-review

• the change is tiny and obvious
• only one or two trivial lines changed
• the user wants immediate formal review instead of cleanup

Workflow

Phase 1: Identify Changes

• If the user gives a base/head range, use that
• If staged changes exist, inspect

  git diff HEAD

  so both staged and unstaged changes are included
• Otherwise use

  git diff

• If there is no git diff, review the most recently modified files the user mentioned or that you edited earlier in the session
• Keep a compact summary of touched files plus the full diff text for the reviewers

Phase 2: Read Local Standards

• Check local instructions first such as

  AGENTS.md

  , repo conventions, and any relevant skills
• Follow existing naming, formatting, and structure in the touched files
• If local conventions conflict with generic cleanup preferences, local conventions win

Phase 3: Launch Three Review Agents in Parallel

explorer

• the full diff
• the touched file list
• the cleanup constraint: no behavior changes, no edits, findings only

• Code reuse review
• Code quality review
• Efficiency review

• references/reuse-reviewer.md
• references/quality-reviewer.md
• references/efficiency-reviewer.md

• Review agents are read-only; they do not edit files
• The main agent aggregates findings and performs the fixes
• Do not spawn multiple worker agents to edit the same touched files in parallel

Phase 4: Fix the Worthwhile Issues

• Wait for all reviewers to finish
• Aggregate findings and remove duplicates
• Fix issues directly if they improve the code without changing behavior
• If a finding is a false positive or not worth the churn, note that and skip it without arguing at length

Phase 5: Verify

• Run the narrowest meaningful verification for the changed area
• Prefer targeted tests first, then lint/build if appropriate
• If no automated verification exists, state that explicitly and mention residual risk
• Briefly summarize what was fixed, or state that the code was already clean enough

Quick Reference

Common Mistakes

• Turning simplification into redesign
• Extracting abstractions too early
• Renaming broadly across unrelated files
• Optimizing for fewer lines instead of easier maintenance
• Skipping verification because the change "looks mechanical"
• Letting all three agents edit code instead of only reporting findings
• Using this skill as a substitute for formal review or spec validation

Upstream Reference

/simplify