code-simplifier

Code Simplifier

Cleanup pass over a session's changes or a named target. Reviews the code in scope, understands how it fits the existing codebase, and makes targeted improvements — modernizing syntax, removing unnecessary complexity, consolidating duplicated logic, catching efficiency issues. Prioritizes codebase cohesion over local perfection.

Core philosophy

Every change must earn its keep. A simplification that doesn't meaningfully improve clarity, correctness, or cohesion is noise. Don't refactor for refactoring's sake. Don't create new files, abstractions, or utilities unless they solve a demonstrated problem. If the existing code works and is readable, leave it alone. The goal is a cohesive codebase, not a pristine one.

Procedure

Phase 1: Set the scope

Two scopes; the caller's wording picks one, and the diff is the default.

• Diff (nothing named): run git status to see the shape of the working tree, then git diff HEAD for all uncommitted changes (staged and unstaged). Untracked files never appear in the diff — list them with git ls-files --others --exclude-standard (git status collapses a new directory to one line) and read them directly. If the diff is empty and there are no untracked files, review the last commit (git diff HEAD~1 HEAD); if that is also empty, say the tree is clean and stop. Don't go hunting through the codebase for files to improve.
• Target (a named path, module, or "the whole codebase"): the named files are the scope, whatever their git state. Work one module or directory at a time and re-run the gate after each, so a large scan never becomes one unverifiable diff. Take the target as named — don't rank or narrow it by commit history.

Phase 2: Understand the surrounding codebase

Don't review changes in isolation. Before any modifications:

1. Read the full files containing changes — not just the diff hunks. Understand imports, surrounding logic, module structure.
2. Identify the project language(s) and select the relevant transformation rules. Discard inapplicable rules.
3. Survey adjacent code — shared utilities, sibling modules, common patterns. You need to know what already exists before deciding something is missing.
4. Run the project's gate once before editing to establish a baseline. Use the gate the project's CLAUDE.md / AGENTS.md names; absent one, take it from package.json scripts — devcheck if present, else check, else the separate typecheck / lint scripts — or a Makefile check target. Python projects gate on uv run ruff check, uv run ruff format --check, and the configured type checker. Add the test suite when the gate doesn't run it — read the script rather than assume (a devcheck often stops at lint and typecheck); without tests, nothing shows behavior survived the pass. In a Bun project that tests with Vitest, run bun run test — bare bun test bypasses the script and runs Bun's own runner. If the gate is already red, say so in the summary and don't attribute the failure to your changes.