Imported from Rosetears520/aili-workflows (.agents/skills/code-simplification/SKILL.md). Install upstream with npx skills add Rosetears520/aili-workflows --skill code-simplification. Copyright stays with the author.

Code Simplification

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

• The user explicitly requests a behavior-preserving simplification/refactor
• A named review finding or accepted task identifies a concrete readability/complexity problem
• 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
• A bounded accepted cleanup identifies 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

ROSE/aili-delivery-flow owns scope, material decisions, approvals, Git actions, and verification. This skill runs one bounded simplification loop and does not invoke review, Git, testing, or another process skill. Return complete, need-user, need-evidence, material-delta, blocked, or Unverified; canonical claim-matched verification wins.

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.

SELF-CHECK EACH CANDIDATE 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?
→ What focused evidence can prove behavior equivalence without changing tests?

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: 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';
}

// UNCLEAR: Chained reduces with inline logic
const result = items.reduce((acc, item) => ({
  ...acc,
  [item.id]: { ...acc[item.id], count: (acc[item.id]?.count ?? 0) + 1 }
}), {});

// CLEAR: Named intermediate step
const countById = new Map<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

Architecture Deepening Checks

Use these terms when deciding whether a simplification should remove, keep, or reshape a boundary:

• Module: a unit with a responsibility and callers.
• Interface: the public surface callers depend on.
• Implementation: the hidden complexity behind the interface.
• Deep module: small interface, meaningful hidden implementation.
• Shallow module: public surface is as complex as the thing it wraps.
• Seam: a boundary where alternative implementations or tests can attach.
• Adapter: implementation behind a seam for a concrete external system or variation.
• Leverage: how much caller complexity disappears because the module exists.
• Locality: how much related behavior stays in one place.

Apply the deletion test: if deleting a module makes the complexity disappear, it was probably a pass-through wrapper. If deleting it spreads complexity across callers, the module is earning its keep.

Do not invent interfaces too early. One adapter usually means a hypothetical seam; two real adapters, or a concrete near-term need, can justify a seam.

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.

🔴 CHECKPOINT · Behavior-Risk Gate

🛑 STOP before editing when a simplification would touch any of these behavior-risky areas:

• public interfaces, exported types, API routes, schemas, migrations, auth, permissions, or persistence
• error handling, retry behavior, ordering, concurrency, caching, validation, or side effects
• performance-critical paths where the simpler version may change complexity or allocation patterns
• code without tests or without enough context to prove equivalent behavior

At this gate, either narrow the change to a behavior-neutral refactor with claim-matched verification or return the exact behavior/scope decision to ROSE. Do not treat a behavior-changing cleanup as simplification.

Step 2: Identify Simplification Opportunities

Scan for these patterns — each one is a concrete signal, not a vague smell:

Structural complexity:

Naming and readability:

Redundancy:

Step 3: Apply a Bounded Simplification

Apply the smallest coherent simplification set whose behavior-equivalence evidence can be isolated. Do not add tests, commits, PR splits, or approval checkpoints after each edit; the canonical owner selects one focused check for the resulting claim.

FOR THE BOUNDED SET:
1. Make only the accepted behavior-preserving edits
2. Inspect the focused diff and selected equivalence evidence
3. Run the canonical owner's smallest claim-matched check once
4. If the check fails, apply at most one targeted repair/recheck or keep the original code and report the blocker

Avoid unrelated cleanup or a broad rewrite. Keep the resulting diff small enough to localize a failed equivalence claim without creating per-edit ceremony.

Failure and Fallback Table

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.

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);

// SIMPLIFY: Redundant boolean return
// Before
function isValid(input: string): boolean {
  if (input.length > 0 && input.length < 100) {
    return true;
  }
  return false;
}
// After
function isValid(input: string): boolean {
  return input.length > 0 && input.length < 100;
}

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}

# SIMPLIFY: Nested conditionals with early return
# Before
def process(data):
    if data is not None:
        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")
# After
def process(data):
    if data is None:
        raise TypeError("Data is None")
    if not data.is_valid():
        raise ValueError("Invalid data")
    if not data.has_permission():
        raise PermissionError("No permission")
    return do_work(data)

React / JSX

// SIMPLIFY: Verbose conditional rendering
// Before
function UserBadge({ user }: Props) {
  if (user.isAdmin) {
    return <Badge variant="admin">Admin</Badge>;
  } else {
    return <Badge variant="default">User</Badge>;
  }
}
// After
function UserBadge({ user }: Props) {
  const variant = user.isAdmin ? 'admin' : 'default';
  const label = user.isAdmin ? 'Admin' : 'User';
  return <Badge variant={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

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 the bounded simplification:

• The canonical owner's smallest behavior-equivalence check passes without modifying tests to excuse a change
• Any broader build/lint/test evidence is run only when required by the exact claim
• The simplification is a focused, reviewable 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)
• The evidence supports only the reported behavior-preserving claim; no automatic review gate was added