/ia-simplifying-code

name: ia-simplifying-code
class: discipline
description: >-
  Simplifies, polishes, and declutters code without changing behavior. Use when
  asked to simplify, clean up, refactor, declutter, remove dead code or AI slop,
  or improve readability. For analysis-only reports without code changes, use
  code-simplicity-reviewer agent.

Simplifying Code

Principles

| Principle | Rule | |-----------|------| | **Preserve behavior** | Output must do exactly what the input did -- no silent feature additions or removals. Specifically preserve: async/sync boundaries (do not convert sync to async or reverse), error propagation paths (do not alter strategy), logging/telemetry/guards/retries that encode operational intent, and domain-specific steps (do not collapse into generic helpers that hide intent) | | **Explicit over clever** | Prefer explicit variables over nested expressions. Readable beats compact | | **Simplicity over cleanliness** | Prefer straightforward code over pattern-heavy "clean" code. Three similar lines beat a premature abstraction | | **Surgical changes** | Touch only what needs simplifying. Match existing style, naming conventions, and formatting of the surrounding code | | **Surface assumptions** | Before changing a block, identify what imports it, what it imports, and what tests cover it. Edit dependents in the same pass |

Process

1. **Read first** -- understand the full file and its dependents before changing anything. Apply Chesterton's Fence: if you see code that looks unnecessary but don't understand why it's there, check `git blame` before removing it. First understand the reason, then decide if the reason still applies. 2. **Identify invariants** -- what must stay the same? Public API, return types, side effects, error behavior 3. **Identify targets** -- find the highest-impact simplification opportunities. Impact = readability and maintainability; prioritize: control flow -> naming -> duplication -> types (see Smell -> Fix table) 4. **Apply in order** -- control flow → naming → duplication → data shaping → types. Structural changes first, cosmetic last 5. **Verify** -- confirm no behavior change: tests pass, types check, imports resolve 6. **Pre-submit scope audit** -- walk every changed line and ask "does the requested task explicitly require this line?" If no, revert it and list it as a follow-up under Residual Risks. Drive-by edits belong in a separate change, not the current patch. For the pre-edit complement on ambiguous-scope requests ("simplify my project"), see `ia-verification-before-completion`'s Scope Confirmation gate.

Smell → Fix

| Smell | Fix | |-------|-----| | Deep nesting (>2 levels) | Guard clauses with early returns | | Long function (>20 lines) | Extract into named functions by responsibility | | Too many parameters (>3) | Group into an options/config object | | Duplicated block (**3+** occurrences) | Extract shared function. Two copies = leave inline; wait for the third | | Magic numbers/strings | Named constants | | Complex conditional | Extract to descriptively-named boolean or function | | Boolean-returning `if/else` (each branch returns a literal `True`/`False`) | Collapse to the boolean expression itself: `return a and b`, not a branch per literal | | Dense transform chain (3+ chained methods) | Break into named intermediates for debuggability | | Dead code / unreachable branches | Delete entirely -- no commented-out code | | Unnecessary `else` after return | Remove `else`, dedent |

AI Slop Removal

When simplifying AI-generated code, specifically target:

• **Redundant comments** that restate the code (`// increment counter` above `counter++`) -- delete them
• **Unnecessary defensive checks** for conditions that cannot occur in context -- remove the guard
• **Gratuitous type casts** (`as any`, `as unknown as T`) -- fix the actual type or use a proper generic
• **Over-abstraction** (factory for 2 objects, wrapper around a single call, util file with 1 function) -- inline the code
• **Inconsistent style** that drifts from the file's existing conventions -- match the file
• **Placeholder stubs** (`// ...`, `// rest of code`, `// similar to above`, `// continue pattern`, `// add more as needed`) -- leave unsimplified code as-is rather than replacing it with stubs
• **Redundant error wrapping** (`catch(e) { throw e; }`, `catch(e) { throw new Error(e.message); }`) that strips the original stack for no reason -- remove the try/catch entirely and let errors propagate
• **Verbose stdlib reimplementations** (hand-rolled loops that replicate `array_filter`, `Array.from`, `Collection::pluck()`, `itertools`) -- replace with the stdlib/framework one-liner, but verify edge-case parity first: empty input, null/None guard, no-match default, zero-value path. The one-liner can silently differ from the loop (an empty-input crash, a missing no-match default, lost ordering) -- a structurally cleaner version that changes behavior on an edge case is not a simplification
• **Hand-maintained guarantees** the platform, framework, or a downstream layer already enforces (a manual retry wrapping a client that already retries, a hand-rolled TTL cache the ORM/query layer already provides, manual null-coalescing on a value the contract guarantees non-null) -- name the layer that owns the guarantee and what the code collapses to without it. Remove only when it preserves every output, error, side-effect, and ordering; cite the test or a direct comparison proving equivalence, since "it's already guaranteed" over-fires easily
• **Copy-paste with variation** -- before proposing a shared abstraction, check whether the duplicated construct can be *eliminated* by deriving it from an existing source of truth (a constant, an existing map, a generated value). Consolidate into a helper only when elimination isn't behavior-preserving *and* the duplication has already cleared the 3-occurrence gate (Smell → Fix); below that, leave it inline per Constraints

Sto