Code Simplification

Code Simplification

You reduce application-code complexity while preserving exact behavior. Goal: faster comprehension for the next reader — not fewer lines for its own sake.

Hard Rules

Never change observable behavior — same inputs, outputs, errors, side effects, ordering. Run tests after each simplification; revert if tests fail or need changing to pass. Default scope: code touched in the current task — no drive-by refactors unless asked. Separate refactoring commits from feature/bugfix commits. Do not simplify code you do not understand — read callers, tests, and blame first.

500 lines touched → prefer codemods/AST tools over manual edits. Protected blocks (simplify-ignore-start / end) must stay hidden — wire hooks/simplify-ignore.sh in Claude Code or read references/simplify-ignore.md.

Workflow

Step 0 — Optional: protect hot paths (Claude Code)

If simplifying code with annotated simplify-ignore blocks, register hooks from hooks/SIMPLIFY-IGNORE.md before reads/edits. Crash recovery: echo '{}' | bash hooks/simplify-ignore.sh.

Step 1 — Understand (Chesterton's Fence)

Before changing anything, answer:

• What is this code's responsibility? Who calls it?
• What edge cases and error paths exist?
• Do tests define expected behavior?
• Why might it look this way? (performance, platform, history)

If you cannot answer, read more context — do not simplify yet.

Step 2 — Identify opportunities

Scan for structural complexity, naming issues, redundancy — see references/simplification-patterns.md for the signal table.

Step 3 — Apply incrementally

For each change: edit → run test suite → commit or continue. One simplification per commit when possible.

Step 4 — Verify the whole

• Is the result genuinely easier to understand?
• Consistent with project conventions (AGENTS.md, neighboring files)?
• Diff reviewable with no unrelated changes?
• If "simplified" code is harder to read, revert.

When NOT to use

• Code already clear — don't simplify for sport
• Performance-critical path where simpler code is measurably slower
• About to delete/rewrite the module entirely
• Skill-library SKILL.md files — use compress-skill / split-skill instead

Gotchas

• Simplification that requires test changes usually changed behavior.
• Inlining a well-named helper hurts readability.
• Fewer lines ≠ simpler (nested ternaries prove this).
• Mixed refactor + feature PRs are hard to review and revert.

Common Rationalizations

Output Format

## Code simplification — [scope]

Before: [brief complexity summary]
Changes: [numbered list]
Tests: [command] → [pass/fail]
Commits: [advised messages]
Reverted: [any attempts that failed verification]

Examples

Verification

• All existing tests pass without modification
• Build/lint clean; no new warnings
• Each change is incremental and reviewable
• Scope limited to task-related files (unless user broadened)
• No error handling removed or weakened
• Simplified code matches project conventions

Red Flags

• Simplification required test changes that alter behavior
• Well-named helper inlined for fewer lines only
• Nested ternaries introduced to reduce line count
• Refactor bundled unrelated behavior changes

Reference Files

• references/simplification-patterns.md: Pattern signal table — read at Step 2.
• references/simplify-ignore.md: Block protection hooks + annotation syntax — read when code has simplify-ignore markers.
• hooks/SIMPLIFY-IGNORE.md: Full setup, examples, limitations (repo root).

Prune Log

Last pruned: 2026-07-04

• No changes — citation audit passed; content current (improve-skills full pass 2026-07-04)

Impact Report

Scope: [files] | Simplifications: N | Tests: [pass/fail]
Reverts: N | Separate refactor commit: [yes/no]