1---2name: simplifying-code-23description: Simplifies, polishes, and declutters code without changing behavior. Use when asked to "simplify code", "clean up code", "polish code", "refactor", "declutter", "reduce complexity", "remove dead code", "remove AI slop", "improve readability", or "tighten up this file".4---56# Simplifying Code78## Principles910| Principle | Rule |11|-----------|------|12| **Preserve behavior** | Output must do exactly what the input did — no silent feature additions or removals. Specifically preserve: async/sync boundaries, error propagation paths, and logging side effects |13| **Explicit over clever** | Prefer explicit variables over nested expressions. Readable beats compact |14| **Simplicity over cleanliness** | Prefer straightforward code over pattern-heavy "clean" code. Three similar lines beat a premature abstraction |15| **Surgical changes** | Touch only what needs simplifying. Match existing style, naming conventions, and formatting of the surrounding code |16| **Surface assumptions** | Before changing a block, identify what imports it, what it imports, and what tests cover it. Edit dependents in the same pass |1718## Process19201. **Read first** — understand the full file and its dependents before changing anything212. **Identify invariants** — what must stay the same? Public API, return types, side effects, error behavior223. **Identify targets** — find the highest-impact simplification opportunities (see Smell → Fix table)234. **Apply in order** — control flow → naming → duplication → data shaping → types. Structural changes first, cosmetic last245. **Verify** — confirm no behavior change: tests pass, types check, imports resolve2526## Smell → Fix2728| Smell | Fix |29|-------|-----|30| Deep nesting (>2 levels) | Guard clauses with early returns |31| Long function (>30 lines) | Extract into named functions by responsibility |32| Too many parameters (>3) | Group into an options/config object |33| Duplicated block (**3+** occurrences) | Extract shared function. Two copies = leave inline; wait for the third |34| Magic numbers/strings | Named constants |35| Complex conditional | Extract to descriptively-named boolean or function |36| Dead code / unreachable branches | Delete entirely — no commented-out code |37| Unnecessary `else` after return | Remove `else`, dedent |3839## AI Slop Removal4041When simplifying AI-generated code, specifically target:4243- **Redundant comments** that restate the code (`// increment counter` above `counter++`) — delete them44- **Unnecessary defensive checks** for conditions that cannot occur in context — remove the guard45- **Gratuitous type casts** (`as any`, `as unknown as T`) — fix the actual type or use a proper generic46- **Over-abstraction** (factory for 2 objects, wrapper around a single call, util file with 1 function) — inline the code47- **Inconsistent style** that drifts from the file's existing conventions — match the file4849## Constraints5051- Only simplify what was requested — do not add features, expand scope, or introduce new dependencies52- Leave unchanged code untouched — do not add comments, docstrings, or type annotations to lines that were not simplified53- If a simplification would make the code harder to understand, skip it54- When unsure whether a block is dead code, ask instead of deleting
iliaal