code-simplification

Files (1)

• SKILL.md

SKILL.md (first lines)

# Code Simplification

> Inspired by the [Claude Code Simplifier plugin](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/code-simplifier/agents/code-simplifier.md). Adapted here as a stack-agnostic, process-driven skill.

Shared reference for `implementer-tdd-agent` and `implementer-coder-agent`'s REFACTOR step.

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

- The REFACTOR step of implementation, once tests are green (or, on the no-test-suite path, once the implementation is functionally complete)
- Code review flags readability or complexity issues
- Deeply nested logic, long functions, or unclear names surface during implementation

**When NOT to use:**

- Code is already clean — don't simplify for the sake of it
- You don't yet understand what the code does — comprehend before you simplify
- The code is performance-critical and the simpler version would be measurably slower

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

```
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, read the project's own conventions and study how neighboring code handles similar patterns — import style, function declaration style, naming, error handling, type-annotation depth. 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.

```
UNCLEAR: dense ternary chain
  const label = isNew ? 'New' : isUpdated ? 'Updated' : isArchived ? 'Archived' : 'Active'

CLEAR: readable branches
  function getStatusLabel(item) {
    if (item.isNew) return 'New'
    if (item.isUpdated) return 'Updated'
    if (item.isArchived) return 'Archived'
    return 'Active'
  }
```

### 4. Maintain Balance

Over-simplification is a real failure mode. Watch for:

- 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 an abstraction that exists for extensibility or testability, not complexity
- Optimizing for line count instead of comprehension speed

### 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 — if you don't understand it, you're not ready to simplify it.

```
BEFORE SIMPLIFYING, ANSWER:
- What is this code's responsibility? What calls it, what does it call?
- What are the edge cases and error paths?
- Do tests define the expected behavior?
- Why might it have been written this way — performance, platform constraint, historical reason?
```

### Step 2: Identify Simplification Opportunities

**Structural complexity:**

| Pattern | Signal | Simplification |
|---------|--------|----------------|
| Deep nesting (3+ levels) | Hard to follow control flow | Extract conditions into guard clauses — e.g. `if (data === null) throw ...; if (!data.isValid()) throw ...;` instead of nested `if/else` |
| Long functions (50+ lines) | Multiple responsibilities | Split into focused functions with descriptive names |
| Nested ternaries | Requires a mental stack to parse | Replace with if/else chains, switch, or a lookup |
| Boolean parameter flags | `doThing(true, false, true)` | Replace with an options object 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` | Rename to describe the content |
| Misleading names | A `get` function that also mutates state | Rename to reflect actual behavior |
| Comments explaining "what" | `// increment counter` above `count++` | Delete — the code is clear enough |
| Comments explaining "why" | `// retry because the API is flaky under load` | Keep — this carries 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 | Remove, after confirming it's truly dead |
| Unnecessary abstraction | A wrapper that adds no value | Inline it, call the underlying function directly |
| Over-engineered pattern | Factory-for-a-factory, strategy-with-one-strategy | Replace with the direct approach |

### Step 3: Apply Changes Incrementally

Make one simplification at a time; treat each as its own verified step inside the REFACTOR step, not bundled with feature or bug-fix changes in the same edit.

- **Tests cover the code** (`implementer-tdd-agent`, or `implementer-coder-agent` once its Test Decision's tests exist): re-run tests after every change. Tests fail → revert and reconsider.
- **No test covers the code** (`implementer-coder-agent` with no tests by decision): re-read the diff for behavior equivalence after every change — there is no test to catch a regression, so each change must be individually small enough to verify by inspection.

From diego81b/kairos-agents-framework, AGPL-3.0.

More from diego81b/kairos-agents-framework