Ultra code simplify

Ultra Code Simplify

Inspired by the Claude Code Simplifier plugin and Ponytail's lazy senior dev mode. 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?"

Approach simplifications with pragmatic YAGNI: before simplifying anything, ask whether it needs to exist at all. Deletion is the simplest form of simplification.

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 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: Dense ternary chain
const label = isNew ? 'New' : isUpdated ? 'Updated' : isArchived ? 'Archived' : 'Active';

// CLEAR: Readable mapping
function getStatusLabel(item: Item): string {
  if (item.isNew) return 'New';
  if (item.isUpdated) return 'Updated';
  if (item.isArchived) return 'Archived';
  return 'Active';
}

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:

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: Apply YAGNI Before Simplification

Before refactoring anything, climb the lazy senior dev ladder:

1. Does this code need to exist at all? If it's unused, dead, or speculative — delete it. Deletion is the simplest simplification.
2. Does the standard library already do this? A hand-rolled utility that duplicates stdlib is not complexity worth preserving — replace it.
3. Does a native platform feature cover it? A custom date picker when <input type="date"> works is not simplification — it's replacement.
4. Can this be one line? A 20-line function that does what one expression does should be shrunk, not refactored into two 10-line functions.

Only after these four checks: proceed to structural simplification.

Step 3: Identify Simplification Opportunities

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

Redundancy:

Pattern	Signal	Simplification
Duplicated logic	Same 5+ lines in multiple places	Extract to a shared function
Dead code	Unreachable branches, unused variables, commented-out blocks	Remove (after confirming it's truly dead)
Unnecessary abstractions	Wrapper that adds no value	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 4: Apply Changes Incrementally

Make one simplification at a time. Run tests after each change.

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

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.

Step 5: Verify the Result

After all simplifications, step back and evaluate:

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.

Language-Specific Guidance

TypeScript / JavaScript

// SIMPLIFY: Unnecessary async wrapper
// Before
async function getUser(id: string): Promise<User> {
  return await userService.findById(id);
}
// After
function getUser(id: string): Promise<User> {
  return userService.findById(id);
}

// SIMPLIFY: Verbose conditional assignment
// Before
let displayName: string;
if (user.nickname) {
  displayName = user.nickname;
} else {
  displayName = user.fullName;
}
// After
const displayName = user.nickname || user.fullName;

// SIMPLIFY: Manual array building
// Before
const activeUsers: User[] = [];
for (const user of users) {
  if (user.isActive) {
    activeUsers.push(user);
  }
}
// After
const activeUsers = users.filter((user) => user.isActive);

Python

# 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}

References

• ultra-ponytail — For persistent YAGNI mode across the entire session. Activates the lazy senior dev ladder continuously.
• ultra-code-review — For reviewing code with the over-engineering checklist.