Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity.
Inspired by the Claude Code Simplifier plugin. Adapted here as a model-agnostic, process-driven skill for any AI coding agent.
Overview
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 a simple test: "Would a new team member understand this faster than the original?"
When to Use
After a feature is working 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
When refactoring code written under time pressure
When consolidating related logic scattered across files
After merging changes that introduced duplication or inconsistency
When NOT to use:
Code is already clean and readable — don't simplify for the sake of it
You don't understand what the code does yet — comprehend before you simplify
The code is performance-critical and the "simpler" version would be measurably slower
You're about to rewrite the module entirely — simplifying throwaway code wastes effort
The Five Principles
1. Preserve Behavior Exactly
Don't change what the code does — only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a simplification preserves behavior, don't make it.
ASK BEFORE EVERY CHANGE:
→ Does this produce the same output for every input?
→ Does this maintain the same error behavior?
→ Does this preserve the same side effects and ordering?
→ Do all existing tests still pass without modification?
2. Follow Project Conventions
Simplification means making code more consistent with the codebase, not imposing external preferences. Before simplifying:
1. Read CLAUDE.md / project conventions
2. Study how neighboring code handles similar patterns
3. Match the project's style for:
- Import ordering and module system
- Function declaration style
- Naming conventions
- Error handling patterns
- Type annotation depth
Simplification that breaks project consistency is not simplification — it's churn.
3. Prefer Clarity Over Cleverness
Explicit code is better than compact code when the compact version requires a mental pause to parse.
// UNCLEAR: Chained reduces with inline logicconst result = items.reduce((acc, item) => ({
...acc,
[item.id]: { ...acc[item.id], count: (acc[item.id]?.count ?? 0) + 1 }
}), {});
// CLEAR: Named intermediate stepconst countById = newMap<string, number>();
for (const item of items) {
countById.set(item.id, (countById.get(item.id) ?? 0) + 1);
}
4. Maintain Balance
Simplification has a failure mode: over-simplification. Watch for these traps:
Inlining too aggressively — removing a helper that gave a concept a name makes the call site harder to read
Combining unrelated logic — two simple functions merged into one complex function is not simpler
Removing "unnecessary" abstraction — some abstractions exist for extensibility or testability, not complexity
Optimizing for line count — fewer lines is not the goal; easier comprehension is
5. Scope to What Changed
Default to simplifying recently modified code. Avoid drive-by refactors of unrelated code unless explicitly asked to broaden scope. Unscoped simplification creates noise in diffs and risks unintended regressions.
The Simplification Process
Step 1: Understand Before Touching (Chesterton's Fence)
Before changing or removing anything, understand why it exists. This is Chesterton's Fence: if you see a fence across a road and don't understand why it's there, don't tear it down. First understand the reason, then decide if the reason still applies.
BEFORE SIMPLIFYING, ANSWER:
- What is this code's responsibility?
- What calls it? What does it call?
- What are the edge cases and error paths?
- Are there tests that define the expected behavior?
- Why might it have been written this way? (Performance? Platform constraint? Historical reason?)
- Check git blame: what was the original context for this code?
If you can't answer these, you're not ready to simplify. Read more context first.
Step 2: Identify Simplification Opportunities
Scan for these patterns — each one is a concrete signal, not a vague smell:
Structural complexity:
Pattern
Signal
Simplification
Deep nesting (3+ levels)
Hard to follow control flow
Extract conditions into guard clauses or helper functions
Long functions (50+ lines)
Multiple responsibilities
Split into focused functions with descriptive names
Nested ternaries
Requires mental stack to parse
Replace with if/else chains, switch, or lookup objects
Boolean parameter flags
doThing(true, false, true)
Replace with options objects or separate functions
Repeated conditionals
Same if check in multiple places
Extract to a well-named predicate function
Naming and readability:
Pattern
Signal
Simplification
Generic names
data, result, temp, val, item
Rename to describe the content: userProfile, validationErrors
Abbreviated names
usr, cfg, btn, evt
Use full words unless the abbreviation is universal (id, url, api)
Misleading names
Function named get that also mutates state
Rename to reflect actual behavior
Comments explaining "what"
// increment counter above count++
Delete the comment — the code is clear enough
Comments explaining "why"
// Retry because the API is flaky under load
Keep these — they carry intent the code can't express
Inline the wrapper, call the underlying function directly
Over-engineered patterns
Factory-for-a-factory, strategy-with-one-strategy
Replace with the simple direct approach
Redundant type assertions
Casting to a type that's already inferred
Remove the assertion
Step 3: Apply Changes Incrementally
Make one simplification at a time. Run tests after each change. Submit refactoring changes separately from feature or bug fix changes. A PR that refactors and adds a feature is two PRs — split them.
FOR EACH SIMPLIFICATION:
1. Make the change
2. Run the test suite
3. If tests pass → commit (or continue to next simplification)
4. If tests fail → revert and reconsider
Avoid batching multiple simplifications into a single untested change. If something breaks, you need to know which simplification caused it.
The Rule of 500: If a refactoring would touch more than 500 lines, invest in automation (codemods, sed scripts, AST transforms) rather than making the changes by hand. Manual edits at that scale are error-prone and exhausting to review.
Step 4: Verify the Result
After all simplifications, step back and evaluate the whole:
COMPARE BEFORE AND AFTER:
- Is the simplified version genuinely easier to understand?
- Did you introduce any new patterns inconsistent with the codebase?
- Is the diff clean and reviewable?
- Would a teammate approve this change?
If the "simplified" version is harder to understand or review, revert. Not every simplification attempt succeeds.
# SIMPLIFY: Verbose dictionary building# Before
result = {}
for item in items:
result[item.id] = item.name
# After
result = {item.id: item.name for item in items}
# SIMPLIFY: Nested conditionals with early return# Beforedefprocess(data):
if data isnotNone:
if data.is_valid():
if data.has_permission():
return do_work(data)
else:
raise PermissionError("No permission")
else:
raise ValueError("Invalid data")
else:
raise TypeError("Data is None")
# Afterdefprocess(data):
if data isNone:
raise TypeError("Data is None")
ifnot data.is_valid():
raise ValueError("Invalid data")
ifnot data.has_permission():
raise PermissionError("No permission")
return do_work(data)
React / JSX
// SIMPLIFY: Verbose conditional rendering// BeforefunctionUserBadge({ user }: Props) {
if (user.isAdmin) {
return<Badgevariant="admin">Admin</Badge>;
} else {
return<Badgevariant="default">User</Badge>;
}
}
// AfterfunctionUserBadge({ user }: Props) {
const variant = user.isAdmin ? 'admin' : 'default';
const label = user.isAdmin ? 'Admin' : 'User';
return<Badgevariant={variant}>{label}</Badge>;
}
// SIMPLIFY: Prop drilling through intermediate components// Before — consider whether context or composition solves this better.// This is a judgment call — flag it, don't auto-refactor.
Common Rationalizations
Rationalization
Reality
"It's working, no need to touch it"
Working code that's hard to read will be hard to fix when it breaks. Simplifying now saves time on every future change.
"Fewer lines is always simpler"
A 1-line nested ternary is not simpler than a 5-line if/else. Simplicity is about comprehension speed, not line count.
"I'll just quickly simplify this unrelated code too"
Unscoped simplification creates noisy diffs and risks regressions in code you didn't intend to change. Stay focused.
"The types make it self-documenting"
Types document structure, not intent. A well-named function explains why better than a type signature explains what.
"This abstraction might be useful later"
Don't preserve speculative abstractions. If it's not used now, it's complexity without value. Remove it and re-add when needed.
"The original author must have had a reason"
Maybe. Check git blame — apply Chesterton's Fence. But accumulated complexity often has no reason; it's just the residue of iteration under pressure.
"I'll refactor while adding this feature"
Separate refactoring from feature work. Mixed changes are harder to review, revert, and understand in history.
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 things to match your 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 large, hard-to-review commit
Refactoring code outside the scope of the current task without being asked
Verification
After completing a simplification pass:
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 was removed or weakened
No dead code was left behind (unused imports, unreachable branches)
A teammate or review agent would approve the change as a net improvement
Limitations
Use this skill only when the task clearly matches its upstream source and local project context.
Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.
