code-simplification

Files (1)

• SKILL.md

SKILL.md (first lines)

# Code Simplification

Adapted from `addyosmani/agent-skills` (MIT), commit `82ceff41ed4d3c644e3dcca8a0514390b2911223`.

## Overview

Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines; it is faster comprehension, safer maintenance, and easier review.

## When to Use

- After a feature works but feels heavier than necessary
- During review when readability or duplication issues show up
- When code has deep nesting, unclear names, or scattered logic
- After a rushed implementation that now needs cleanup

## Core Rules

### Preserve Behavior Exactly

Do not change outputs, side effects, ordering, or error behavior. If you are not sure a simplification is behavior-preserving, stop and gather more context first.

### Follow Project Conventions

Simplification should make code more consistent with the repository, not more consistent with personal taste.

### Prefer Clarity Over Cleverness

Avoid dense ternaries, over-generalized abstractions, and compressed logic that requires a second reading.

### Scope to What Changed

Default to simplifying the code you are already touching. Avoid unrelated cleanup unless explicitly asked.

## Simplification Process

### Step 1: Understand Before Changing

Apply Chesterton's Fence.

- What is this code responsible for?
- Why might it have been written this way?
- What tests define its current behavior?

### Step 2: Identify the Simplification

Look for:

- deep nesting
- long functions with mixed responsibilities
- duplicate logic
- generic or misleading names
- wrappers or abstractions that add no value

### Step 3: Apply Small Changes

Make one simplification at a time and verify after each one.

- simplify the control flow
- extract a well-named helper
- inline an unnecessary wrapper
- remove dead code only when you understand it

### Step 4: Re-evaluate the Whole

After the refactor, ask whether a new teammate would understand the new version faster than the old one.

## Common Rationalizations

| Rationalization | Reality |
|---|---|
| "Fewer lines is always simpler" | A dense one-liner can be harder to understand than a clear five-line block. |
| "I will simplify this unrelated code while I am here" | Drive-by refactors create noisy diffs and hidden regression risk. |
| "This abstraction might be useful later" | Speculative abstractions are complexity without current value. |

## Red Flags

- Tests need to change just to preserve the simplification
- Error handling disappears because it looks noisy
- Renames follow personal taste instead of repo conventions
- The simplified version is harder to review than the original

## Verification

- [ ] Existing tests still pass without semantic changes
- [ ] Build succeeds
- [ ] No error handling was weakened
- [ ] Diff stays focused on the targeted simplification

## Anti-Rationalization Table

| Excuse | Counter |
|--------|---------|
| "Fewer lines is always simpler" | A dense one-liner can be harder to understand than a clear five-line block. |
| "I'll simplify this unrelated code while I'm here" | Drive-by refactors create noisy diffs and hidden regression risk. |
| "This abstraction might be useful later" | Speculative abstractions are complexity without current value. |
| "The code works, why touch it" | Working code that is hard to understand is a maintenance liability. |
| "I'll add tests after simplifying" | Simplification without tests risks silently changing behavior. Tests first. |

From v1truv1us/ai-eng-system, MIT.

More from v1truv1us/ai-eng-system