Simplify

Code Simplification

Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines — it's code that is easier to read, understand, modify, and debug. Every simplification must pass one test: "Would a new team member understand this faster than the original?"

When to use

• After a feature works and tests pass, but the implementation feels heavier than it needs to be
• During code review when readability or complexity issues are flagged
• When you encounter deeply nested logic, long functions, or unclear names
• After merging changes that introduced duplication or inconsistency
• Triggers on "simplify", "too complex", "refactor for clarity"

Not for: code you don't fully understand yet — comprehend before you simplify. Performance-critical code where the "simpler" version would be measurably slower. Throwaway code about to be rewritten entirely. Cross-module structural changes — extracting/moving modules, redrawing dependency boundaries, splitting or merging files → use refactoring. Designing where a seam or deep module should go (producing an audit, not executing) → use codebase-design. Single-file clarity stays here: naming, nesting, dead code.

Steps

1. Understand before touching (Chesterton's Fence)

Before changing or removing anything, understand why it exists. If you see a fence across a road and don't understand why it's there, don't tear it down.

• What is this code's responsibility? What calls it, what does it call?
• What are the edge cases and error paths? Are there tests defining expected behavior?
• Why might it have been written this way — performance? platform constraint? historical reason? Check git blame for the original context.

If you can't answer these, you're not ready. Read more context first.

2. Identify simplification opportunities

Scan for concrete signals — each is a specific pattern, not a vague smell. The full tables (structural complexity, naming, redundancy) with examples are in references/opportunities.md. Summary:

• Structural: deep nesting (3+ levels), long functions (50+ lines), nested ternaries, boolean parameter flags, repeated conditionals.
• Naming: generic names (data, temp, result), abbreviations (usr, cfg), misleading names, comments restating "what" instead of "why".
• Redundancy: duplicated logic, dead code, unnecessary abstractions, over-engineered patterns (factory-for-a-factory), redundant type assertions.

3. Apply the five principles

1. Preserve behavior exactly. Same output for every input, same error behavior, same side effects and ordering, all existing tests pass without modification. If you're not sure a simplification preserves behavior, don't make it.
2. Follow project conventions. Read CLAUDE.md; study how neighboring code handles similar patterns. Simplification that breaks project consistency is churn, not simplification.
3. Prefer clarity over cleverness. Explicit code beats compact code when the compact version requires a mental pause to parse. A 1-line nested ternary is not simpler than a 5-line if/else.
4. Maintain balance. Over-simplification is a failure mode: inlining too aggressively (removing a concept's name), combining unrelated logic into one complex function, removing abstractions that exist for extensibility or testability, optimizing for line count.
5. Scope to what changed. Default to recently modified code. Avoid drive-by refactors of unrelated code unless explicitly asked to broaden scope — unscoped simplification creates noisy diffs and risks regressions.

4. Apply changes incrementally

One simplification at a time. Run the test suite after each change. The incremental-test, separate-PR, and Rule-of-500 rules are in §9 (behavior-preserving change discipline) of engineering-principles.md — apply them here.

• Make the change → run the suite → pass: continue to the next; fail: revert and reconsider.
• Avoid batching multiple simplifications into one untested change. If something breaks, you need to know which simplification caused it.

5. Verify the result

Step back and evaluate the whole. Compare before and after:

• Is the simplified version genuinely easier to understand?
• Did you introduce any patterns inconsistent with the codebase?
• Is the diff clean and reviewable? Would a teammate approve?

If the "simplified" version is harder to understand or review than the original, revert. Not every simplification attempt succeeds.

Verify

• [ ] All existing tests pass without modification
• [ ] Build succeeds with no new warnings; linter/formatter passes (no style regressions)
• [ ] Each simplification is a reviewable, incremental change; the diff is clean — no unrelated changes mixed in
• [ ] Simplified code follows project conventions (checked against CLAUDE.md or equivalent)
• [ ] No error handling removed or weakened; no dead code left behind (unused imports, unreachable branches)
• [ ] The "simplified" code is genuinely easier to understand than the original

Red flags: simplification that requires modifying tests to pass (you likely changed behavior); "simplified" code that is longer and harder to follow than the original; renaming to match personal preferences rather than project conventions; removing error handling because "it makes the code cleaner"; simplifying code you don't fully understand; batching many simplifications into one hard-to-review commit; refactoring outside the current task's scope without being asked.

References

• [${CLAUDEPLUGINROOT}/references/engineering-principles.md](${CLAUDEPLUGINROOT}/references/engineering-principles.md) — shared discipline (enforce simplicity, surgical scope, verify don't assume)
• [${CLAUDEPLUGINROOT}/references/clean-code.md](${CLAUDEPLUGINROOT}/references/clean-code.md) — meaningful names, small functions, comments, error handling (Uncle Bob)
• [references/opportunities.md](references/opportunities.md) — full simplification-opportunities tables (structural / naming / redundancy) + language-specific examples (TypeScript, Python, React/JSX)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: int2t05
• Source: int2t05/engineering-skills
• License: MIT

Install and usage instructions live in the source repository linked above.